Merge origin/master (regenerate the event producer-consumer graph)

packages/client/runtime/src/client/contract/session.ts

@@ -0,0 +1,56 @@
+/**
+ * The outward session face. Feature packages never see the concrete Session
+ * class: components read conversation state through `useSession` (the
+ * ObservableSnapshot half), and orchestration code calls the behavior verbs
+ * below — nothing else. Widening this interface is the explicit act of
+ * widening what features may do to a session (and what every test fixture
+ * must stub); runtime-internal entry points (history staging, wire-frame
+ * dispatch) stay on the class, invisible out here.
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
+import type { RpcResult, SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { ConversationSnapshot } from '../sessions/conversation.ts'
+import type { ObservableSnapshot } from './store.ts'
+
+/** Key-addressed projection read face (the useProjection resolution path; see ProjectionValueStore). */
+export interface ProjectionsFace {
+  /**
+   * The identity-stable bare observable for one projection key (absence is
+   * an `undefined` snapshot, never a missing face).
+   * @param key - projection key.
+   * @returns the key's value face.
+   */
+  faceOf(key: string): ObservableSnapshot<unknown>
+}
+
+/** Identity plus the behavior verbs features may invoke on a session. */
+export interface ISession {
+  /** The session's host identity (agent id — same axis). */
+  readonly sessionId: SessionId
+  /** Host-computed projection values by key (the useProjection seat). */
+  readonly projections: ProjectionsFace
+  /**
+   * Send a prompt into the session.
+   * @param content - model-facing content blocks.
+   * @param mode - 'queue' appends a turn; 'steer' interrupts the running one.
+   * @returns acceptance, or the business error (also mirrored into snapshot.promptError).
+   */
+  prompt(content: ContentBlock[], mode: 'queue' | 'steer'): Promise<RpcResult<{ accepted: true }>>
+  /**
+   * Cancel the running turn.
+   * @returns acceptance, or the business error.
+   */
+  cancel(): Promise<RpcResult<{ accepted: true }>>
+  /**
+   * Extend the history window backwards (older messages pagination).
+   * @returns completion; failures land in snapshot.openState/loadingOlder.
+   */
+  loadOlder(): Promise<void>
+}
+
+/**
+ * The full outward face: behavior verbs plus the conversation read side
+ * (the `useSession` hook source). This is the type carried by
+ * `SessionBinding.session` and the provide channel.
+ */
+export type SessionFace = ISession & ObservableSnapshot<ConversationSnapshot>

packages/client/runtime/src/client/contract/sessions-port.ts

@@ -0,0 +1,47 @@
+/**
+ * Cross-domain sessions face: the contract surface sibling domains (today:
+ * workspaces) consume instead of the sessions implementation. The sessions
+ * domain satisfies it structurally — SessionsService is assignable, checked
+ * wherever the assembly layer or a test injects the real service — so
+ * widening this face is the explicit act of widening the inter-domain
+ * dependency.
+ */
+
+import type { SessionId, WorkspaceId } from '@deepseek-ai/dsh-client-connection/client'
+import type { ObservableSnapshot } from './store.ts'
+
+/** Session-list row facts sibling domains read: recency, blank-reuse eligibility, and its cwd canon. */
+export interface SessionsPortSummary {
+  id: SessionId
+  /** Empty-log bit (blank sessions are reused by New Session instead of minting another). */
+  blank: boolean
+  cwd?: string
+  updatedAt: number
+}
+
+/** Session-list facts sibling domains read: readiness, selection, and the row map. */
+export interface SessionsPortList {
+  ids: SessionId[]
+  byId: Record<SessionId, SessionsPortSummary>
+  current: SessionId | undefined
+  phase: 'pending' | 'ready'
+}
+
+/** The sessions-service face injected into sibling domains. */
+export interface SessionsPort {
+  /** Observable list snapshot (read face only; writes stay inside the sessions domain). */
+  readonly list: ObservableSnapshot<SessionsPortList>
+  /**
+   * Create a session on the host.
+   * @param opts - target workspace.
+   * @returns the new session id.
+   */
+  create(opts: { workspaceId: WorkspaceId }): Promise<SessionId>
+  /**
+   * Select a session as current.
+   * @param id - session id (must exist in the list store).
+   */
+  open(id: SessionId): void
+  /** Clear the current selection into the no-session view state. */
+  clear(): void
+}

packages/client/runtime/src/client/contract/sessions.ts

@@ -0,0 +1,64 @@
+/**
+ * The outward sessions-service face — what `ctx.sessions` exposes to feature
+ * packages and the renderer host, and therefore exactly what the test
+ * runtime's sessions double must implement. Wire-pump entry points
+ * (handleMuxEnvelope/handleConnected/refresh) and runtime internals stay on
+ * the concrete class; cross-domain consumers keep the narrower
+ * [SessionsPort](./sessions-port.ts). Widening this interface is the
+ * explicit act of widening what features may do to the sessions domain.
+ */
+import type { Context } from 'cordis'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { HostObservable, SessionMaybeProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
+import type {
+  SessionBinding, SessionListState, SessionProvideDescriptor,
+} from '../sessions/service.ts'
+import type { SessionFace } from './session.ts'
+import type { ObservableSnapshot } from './store.ts'
+
+/** The sessions-service face injected as `ctx.sessions`. */
+export interface ISessions {
+  /** The useSessions standard feed (list rows + current selection; read face — writes stay inside the domain). */
+  readonly list: ObservableSnapshot<SessionListState>
+  /** Atomic current-session provide projection (the renderer host's `sessions.provideInfo` feed). */
+  readonly currentProvideInfo: HostObservable<SessionMaybeProvideInfo>
+  /**
+   * Select a session as current.
+   * @param id - session id (must exist in the list; unknown ids fail loud).
+   */
+  open(id: SessionId): void
+  /** Clear the current selection into the no-session view state. */
+  clear(): void
+  /**
+   * Register a per-session standard-props provider (hooks become `use<Name>`
+   * selector hooks on the render side; props spread verbatim).
+   * @param descriptor - static member roster plus per-session resolver.
+   * @returns disposer removing the provider.
+   */
+  provide(descriptor: SessionProvideDescriptor): () => void
+  /**
+   * Resolve an Agent-scoped context view (use-and-discard).
+   * @param id - session id.
+   * @returns scoped ctx, or undefined for a session neither listed nor already scoped.
+   */
+  scope(id: SessionId): Context | undefined
+  /**
+   * Read the Agent scope tag off a context (service-method seam: fetch
+   * bundles must reach scope resolution through ctx.sessions).
+   * @param ctx - any client context.
+   * @returns the session id, or undefined on root contexts.
+   */
+  scopeOf(ctx: Context): SessionId | undefined
+  /**
+   * Resolve the session face behind an Agent-scoped context.
+   * @param ctx - an Agent-scoped context.
+   * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
+   */
+  sessionOf(ctx: Context): SessionFace | undefined
+  /**
+   * Resolve the stable session binding (scope-addressed assembly feed).
+   * @param id - session id.
+   * @returns binding, or undefined for a session neither listed nor already scoped.
+   */
+  binding(id: SessionId): SessionBinding | undefined
+}

packages/client/runtime/src/client/contract/workspaces.ts

@@ -0,0 +1,65 @@
+/**
+ * The outward workspaces-service face — what `ctx.workspaces` exposes to
+ * feature packages and the renderer host, and therefore exactly what the
+ * test runtime's workspaces double must implement. Wire-pump entry points
+ * (handleHostEnvelope/handleConnected/refresh/startInitialSelection) stay on
+ * the concrete class. Widening this interface is the explicit act of
+ * widening what features may do to the workspaces domain.
+ */
+import type { SessionId, WorkspaceId, WorkspaceView } from '@deepseek-ai/dsh-client-connection/client'
+import type { WorkspaceListState } from '../workspaces/service.ts'
+import type { ObservableSnapshot } from './store.ts'
+
+/** The workspaces-service face injected as `ctx.workspaces`. */
+export interface IWorkspaces {
+  /** The useWorkspaces standard feed (read face — writes stay inside the domain). */
+  readonly list: ObservableSnapshot<WorkspaceListState>
+  /**
+   * Connect a Workspace to its reusable or freshly created blank session.
+   * @param workspaceId - target workspace.
+   * @returns the connected session id.
+   */
+  connectWorkspace(workspaceId: WorkspaceId): Promise<SessionId>
+  /**
+   * The New Session flow: connect the target (or recent) Workspace and open
+   * the resulting session; failures surface on the session list state.
+   * @param workspaceId - explicit target; omitted uses the recency projection.
+   */
+  startSession(workspaceId?: WorkspaceId): void
+  /**
+   * Create a Workspace by name or register an existing path.
+   * @param input - exactly one Host create spelling.
+   * @returns the created or idempotently resolved Workspace.
+   */
+  create(input: { name: string } | { path: string }): Promise<WorkspaceView>
+  /**
+   * Open the Host's native directory picker.
+   * @returns the selected path, or null when the user cancelled.
+   */
+  pickDirectory(): Promise<string | null>
+  /**
+   * Open a filesystem path with the Host operating system's default application.
+   * @param path - absolute or host-resolvable path.
+   */
+  openPath(path: string): Promise<void>
+  /**
+   * Rename a Workspace.
+   * @param workspaceId - target workspace.
+   * @param title - the new display title.
+   * @returns the updated Workspace view.
+   */
+  rename(workspaceId: WorkspaceId, title: string): Promise<WorkspaceView>
+  /**
+   * Delete a Workspace (its sessions fall back to the unaccounted group).
+   * @param workspaceId - target workspace.
+   */
+  delete(workspaceId: WorkspaceId): Promise<void>
+  /**
+   * Move an accounted session within/into a Workspace's ordered list.
+   * @param workspaceId - target workspace.
+   * @param sessionId - accounted session to move.
+   * @param beforeSessionId - accounted anchor to insert before; omitted appends.
+   * @returns the updated Workspace view.
+   */
+  insertSessionBefore(workspaceId: WorkspaceId, sessionId: SessionId, beforeSessionId?: SessionId): Promise<WorkspaceView>
+}

packages/client/runtime/src/client/index.ts

@@ -12,10 +12,17 @@ import type { UseProjection } from './sessions/projection-store.ts'
 export { SlotsService } from './slots.ts'
 export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionsService, scopeOf, workspaceTitleOf } from './sessions/service.ts'
+// The provide channel is shared with the client test runtime (one
+// materialization/projection implementation; no test-side mirror to drift).
+export { SessionProvideChannel } from './sessions/provide.ts'
+export type { SessionProvideChannelHost } from './sessions/provide.ts'
 export { createScope } from './agents/scope.ts'
 export type { AgentScopeHandle } from './agents/scope.ts'
 export { WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
 export type { Session } from './sessions/session.ts'
+export type { ISession, ProjectionsFace, SessionFace } from './contract/session.ts'
+export type { ISessions } from './contract/sessions.ts'
+export type { IWorkspaces } from './contract/workspaces.ts'
 export type {
   SessionBinding, SessionListState, SessionProvideContribution, SessionProvideDescriptor, SessionSummary,
 } from './sessions/service.ts'
@@ -109,8 +116,10 @@ declare module 'cordis' {
   }
   interface Context {
     slots: import('./slots.ts').SlotsService
-    sessions: import('./sessions/service.ts').SessionsService
-    workspaces: import('./workspaces/service.ts').WorkspacesService
+    /** The outward face only; the concrete service stays inside the runtime. */
+    sessions: import('./contract/sessions.ts').ISessions
+    /** The outward face only; the concrete service stays inside the runtime. */
+    workspaces: import('./contract/workspaces.ts').IWorkspaces
   }
 }
 

packages/client/runtime/src/client/sessions/manager.ts

@@ -212,6 +212,19 @@ export class SessionManager {
             session.handleBlank(s.blank)
             session.handleRunning(s.running)
           }
+          // Seed each row's projection baseline into the per-session value
+          // store (cold titles surface without opening the session). Per-key
+          // apply, not seed(): the list block is a partial baseline — the
+          // cold cache serves only version-matching keys — so an absent key
+          // must not clear; higher-seq-wins still keeps a stale list block
+          // from overwriting a newer push frame or tail baseline.
+          for (const s of result.value.items) {
+            const block = s.projections
+            if (block === undefined) continue
+            const store = this.projectionStore(s.sessionId)
+            const values = block.values as Record<string, unknown>
+            for (const key of Object.keys(values)) store.apply(key, values[key], block.asOfSeq)
+          }
         } else {
           this.listState = 'error'
           this.listError = result.error

packages/client/runtime/src/client/sessions/provide.ts

@@ -0,0 +1,190 @@
+/**
+ * The session standard-props provide channel: provider roster, bundle
+ * materialization (fail-loud on undeclared/missing/duplicate members), the
+ * static no-session projection, and the atomic current-session projection
+ * observable. One implementation — SessionsService drives it from wire
+ * truth, the test runtime's sessions double drives it from fixtures — so
+ * the materialization rules and the projection semantics cannot drift
+ * between production and the test bench.
+ */
+import type { HostObservable, SessionMaybeProvideInfo, SessionProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionBinding, SessionProvideDescriptor } from './service.ts'
+
+/** The owner-side hooks: how the channel reaches the owner's live bundles and current selection. */
+export interface SessionProvideChannelHost {
+  /**
+   * Re-materialize every already-materialized bundle against the new roster
+   * (call {@link SessionProvideChannel.materializeInfo} per live binding).
+   * Lazily-materialized sessions pick the new roster up on first resolve.
+   */
+  rebuildBundles(): void
+  /** Resolve the current selection's bundle (the owner's maybe-provide lookup). */
+  resolveCurrent(): SessionMaybeProvideInfo
+}
+
+/**
+ * Provider roster + materialization + current projection. The channel owns
+ * every rule a provider contribution must satisfy; owners keep only their
+ * per-session bundle storage and the definition of "current".
+ */
+export class SessionProvideChannel {
+  private readonly providers: SessionProvideDescriptor[] = []
+  private maybeInfoCache: SessionMaybeProvideInfo
+  /** Latest published current bundle (identity comparison dedupes republish). */
+  private currentSnapshot: SessionMaybeProvideInfo
+  /** Projection subscribers (plain cell: bundles hold live session sources, so no store freeze may touch them). */
+  private readonly listeners = new Set<() => void>()
+
+  /**
+   * Atomic current-session provide projection: selection changes and
+   * provider-roster changes publish through this one source, so a roster
+   * change under a stable current id republishes the bundle instead of
+   * stranding mounted entries.
+   */
+  readonly currentProvideInfo: HostObservable<SessionMaybeProvideInfo>
+
+  /**
+   * @param host - owner-side bundle storage and current-selection resolution.
+   */
+  constructor(private readonly host: SessionProvideChannelHost) {
+    // The runtime's own contribution comes first: useSession rides the same
+    // provide channel every plugin uses (no renderer special case).
+    this.providers.push({
+      hooks: ['session'],
+      resolve: binding => ({ hooks: { session: binding.session } }),
+    })
+    this.maybeInfoCache = this.materializeMaybeInfo()
+    this.currentSnapshot = this.maybeInfoCache
+    this.currentProvideInfo = {
+      getSnapshot: () => this.currentSnapshot,
+      subscribe: (fn) => {
+        this.listeners.add(fn)
+        return () => { this.listeners.delete(fn) }
+      },
+    }
+  }
+
+  /** The static no-session projection under the current roster (declared names present, values undefined). */
+  get maybeInfo(): SessionMaybeProvideInfo {
+    return this.maybeInfoCache
+  }
+
+  /**
+   * Register a per-session standard-props provider (see
+   * SessionsService.provide for the product contract). Live bundles rebuild
+   * immediately; misdeclared providers fail loud here, at the registration
+   * edge, and the registration rolls back — the channel never stays on a
+   * roster it cannot materialize.
+   * @param descriptor - static member roster plus per-session resolver.
+   * @returns disposer removing the provider.
+   */
+  provide(descriptor: SessionProvideDescriptor): () => void {
+    this.providers.push(descriptor)
+    try {
+      this.applyRosterChange()
+    } catch (error) {
+      this.providers.splice(this.providers.indexOf(descriptor), 1)
+      // Restore the previous (valid) roster's bundles; cannot rethrow — the
+      // pre-push roster materialized successfully before.
+      this.applyRosterChange()
+      throw error
+    }
+    return () => {
+      const at = this.providers.indexOf(descriptor)
+      if (at >= 0) this.providers.splice(at, 1)
+      this.applyRosterChange()
+    }
+  }
+
+  /**
+   * Re-derive the current selection's bundle and publish it when it changed.
+   * Bundles are identity-stable per (scope, roster) materialization, so an
+   * identity compare is exact; synchronous notify — call sites (the owner's
+   * list subscription, provide()) already sit behind their own batching or
+   * registration edges.
+   */
+  publishCurrent(): void {
+    const next = this.host.resolveCurrent()
+    if (next === this.currentSnapshot) return
+    this.currentSnapshot = next
+    for (const fn of [...this.listeners]) {
+      try {
+        fn()
+      } catch (error) {
+        // Contain subscriber failures: this notify runs inside the list
+        // notification, where a throwing render-side subscriber would starve
+        // later listeners and abort the projection pass that scheduled it.
+        console.error('sessions.currentProvideInfo subscriber failed:', error)
+      }
+    }
+  }
+
+  /**
+   * Materialize the standard-props bundle for one session (fails loud on
+   * undeclared, missing, and duplicate member names).
+   * @param binding - session assembly handle fed to every resolver.
+   * @returns the materialized bundle (identity-stable until the next materialization).
+   */
+  materializeInfo(binding: SessionBinding): SessionProvideInfo {
+    const hooks: Record<string, HostObservable<unknown>> = {}
+    const props: Record<string, unknown> = {}
+    for (const descriptor of this.providers) {
+      const contribution = descriptor.resolve(binding)
+      const contributedHooks = contribution.hooks ?? {}
+      const contributedProps = contribution.props ?? {}
+      for (const name of Object.keys(contributedHooks)) {
+        if (!(descriptor.hooks ?? []).includes(name)) {
+          throw new Error(`sessions.provide: undeclared hook "${name}"`)
+        }
+      }
+      for (const name of Object.keys(contributedProps)) {
+        if (!(descriptor.props ?? []).includes(name)) {
+          throw new Error(`sessions.provide: undeclared prop "${name}"`)
+        }
+      }
+      for (const name of descriptor.hooks ?? []) {
+        const source = contributedHooks[name]
+        if (source === undefined) throw new Error(`sessions.provide: missing hook "${name}"`)
+        if (Object.hasOwn(hooks, name)) throw new Error(`sessions.provide: duplicate hook "${name}"`)
+        hooks[name] = source
+      }
+      for (const name of descriptor.props ?? []) {
+        if (!Object.hasOwn(contributedProps, name)) throw new Error(`sessions.provide: missing prop "${name}"`)
+        if (Object.hasOwn(props, name)) throw new Error(`sessions.provide: duplicate prop "${name}"`)
+        props[name] = contributedProps[name]
+      }
+    }
+    return {
+      sessionId: binding.sessionId,
+      hooks,
+      props,
+      // The useProjection seat: key-addressed bare value faces off the
+      // session's projection store (open key space — never a static roster member).
+      projections: { faceOf: key => binding.session.projections.faceOf(key) },
+    }
+  }
+
+  /** Rebuild the static projection and the owner's live bundles, then republish the current one. */
+  private applyRosterChange(): void {
+    this.maybeInfoCache = this.materializeMaybeInfo()
+    this.host.rebuildBundles()
+    this.publishCurrent()
+  }
+
+  /** Build the static no-session kit and reject duplicate declared names. */
+  private materializeMaybeInfo(): SessionMaybeProvideInfo {
+    const hooks: Record<string, undefined> = {}
+    const props: Record<string, undefined> = {}
+    for (const descriptor of this.providers) {
+      for (const name of descriptor.hooks ?? []) {
+        if (Object.hasOwn(hooks, name)) throw new Error(`sessions.provide: duplicate hook "${name}"`)
+        hooks[name] = undefined
+      }
+      for (const name of descriptor.props ?? []) {
+        if (Object.hasOwn(props, name)) throw new Error(`sessions.provide: duplicate prop "${name}"`)
+        props[name] = undefined
+      }
+    }
+    return { sessionId: undefined, hooks, props } // no projections face: every key reads absent without a session
+  }
+}

packages/client/runtime/src/client/sessions/service.ts

@@ -22,9 +22,12 @@ import type {
 } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
+import type { SessionFace } from '../contract/session.ts'
+import type { ISessions } from '../contract/sessions.ts'
 import { createScope, scopeOf as scopeTagOf } from '../agents/scope.ts'
 import { SessionManager } from './manager.ts'
 import type { SessionListPhase } from './manager.ts'
+import { SessionProvideChannel } from './provide.ts'
 import type { Session } from './session.ts'
 
 /** Session list row projected from the host list RPC plus live stream increments. */
@@ -79,7 +82,8 @@ export class SessionCreateError extends Error {
 /** Session assembly handle for SessionProvider/inject factories (identity-stable per session). */
 export interface SessionBinding {
   readonly sessionId: SessionId
-  readonly session: Session
+  /** The outward session face only — feature code never sees the concrete class. */
+  readonly session: SessionFace
   readonly ctx: Context
 }
 
@@ -119,6 +123,8 @@ interface ScopeRecord {
   fiber: Fiber
   ctx: Context
   binding: SessionBinding
+  /** The concrete Session for runtime-internal entry points (staging open()); the binding carries only the outward face. */
+  session: Session
   /** Render-layer standard-props bundle (identity-stable per scope; the renderer's per-info caches key off it). */
   provideInfo: SessionProvideInfo
 }
@@ -146,7 +152,7 @@ export interface SessionProvideDescriptor {
 }
 
 /** Root sessions service: list store, current selection, object-layer manager, scope tree, bindings, ancestry. */
-export class SessionsService {
+export class SessionsService implements ISessions {
   /** List snapshot store (list RPC + host stream increments; re-pulled on reconnect) — the useSessions standard feed, current included. */
   readonly list: SnapshotStore<SessionListState>
   /** The object-layer instance cluster and frame dispatch entry. */
@@ -170,14 +176,8 @@ export class SessionsService {
   private readonly selection: SnapshotStore<{ sessionId?: SessionId }>
 
   private readonly scopes = new Map<SessionId, ScopeRecord>()
-  /** Registered per-session standard-props providers, in registration order. */
-  private readonly providers: SessionProvideDescriptor[] = []
-  /** Static no-session projection, rebuilt only when the provider roster changes. */
-  private maybeInfo: SessionMaybeProvideInfo
-  /** Latest published {@link SessionsService.currentProvideInfo} bundle (identity comparison dedupes republish). */
-  private currentProvideInfoSnapshot: SessionMaybeProvideInfo
-  /** currentProvideInfo subscribers (plain cell: bundles hold live Session sources, so no store freeze may touch them). */
-  private readonly currentProvideInfoListeners = new Set<() => void>()
+  /** The provide channel (roster, materialization rules, current projection) — shared with the test runtime's double. */
+  private readonly provideChannel: SessionProvideChannel
   /**
    * The staged session id — follows `list.current` exactly, holding its last
    * defined value across masked gaps (a transiently absent selection blanks
@@ -212,23 +212,17 @@ export class SessionsService {
     // The current-provide projection follows the same current writes.
     this.list.subscribe(() => {
       this.followCurrent()
-      this.updateCurrentProvideInfo()
+      this.provideChannel.publishCurrent()
     })
-    // The runtime's own contribution comes first: useSession rides the same
-    // provide channel every plugin uses (no renderer special case).
-    this.providers.push({
-      hooks: ['session'],
-      resolve: binding => ({ hooks: { session: binding.session } }),
-    })
-    this.maybeInfo = this.materializeMaybeProvideInfo()
-    this.currentProvideInfoSnapshot = this.maybeInfo
-    this.currentProvideInfo = {
-      getSnapshot: () => this.currentProvideInfoSnapshot,
-      subscribe: (fn) => {
-        this.currentProvideInfoListeners.add(fn)
-        return () => { this.currentProvideInfoListeners.delete(fn) }
+    this.provideChannel = new SessionProvideChannel({
+      rebuildBundles: () => {
+        for (const record of this.scopes.values()) {
+          record.provideInfo = this.provideChannel.materializeInfo(record.binding)
+        }
       },
-    }
+      resolveCurrent: () => this.maybeProvideInfo(this.list.getSnapshot().current),
+    })
+    this.currentProvideInfo = this.provideChannel.currentProvideInfo
     rootCtx.reflect.provide('sessions', this, undefined)
   }
 
@@ -243,105 +237,10 @@ export class SessionsService {
    * @returns disposer removing the provider (already-materialized bundles keep their members until their scope drops).
    */
   provide(descriptor: SessionProvideDescriptor): () => void {
-    this.providers.push(descriptor)
     // Scopes may already exist (boot order: the list lands and resolves
-    // scopes before later plugins register) — their bundles must include
-    // every provider by first render, so re-materialize on roster change.
-    this.rematerializeProvideBundles()
-    return () => {
-      const at = this.providers.indexOf(descriptor)
-      if (at >= 0) this.providers.splice(at, 1)
-      this.rematerializeProvideBundles()
-    }
-  }
-
-  /** Rebuild every live scope's standard-props bundle after a provider roster change. */
-  private rematerializeProvideBundles(): void {
-    this.maybeInfo = this.materializeMaybeProvideInfo()
-    for (const record of this.scopes.values()) {
-      record.provideInfo = this.materializeProvideInfo(record.binding)
-    }
-    this.updateCurrentProvideInfo()
-  }
-
-  /**
-   * Re-derive the current selection's provide bundle and publish it when it
-   * changed. Bundles are identity-stable per (scope, roster)
-   * materialization, so an identity compare is exact; synchronous notify —
-   * both call sites (list.subscribe, provide()) already sit behind their own
-   * batching or registration edges.
-   */
-  private updateCurrentProvideInfo(): void {
-    const next = this.maybeProvideInfo(this.list.getSnapshot().current)
-    if (next === this.currentProvideInfoSnapshot) return
-    this.currentProvideInfoSnapshot = next
-    for (const fn of [...this.currentProvideInfoListeners]) {
-      try {
-        fn()
-      } catch (error) {
-        // Contain subscriber failures: this notify runs inside the list
-        // notification, where a throwing render-side subscriber would starve
-        // later listeners and abort the projection pass that scheduled it.
-        console.error('sessions.currentProvideInfo subscriber failed:', error)
-      }
-    }
-  }
-
-  /** Build the static no-session kit and reject duplicate declared names. */
-  private materializeMaybeProvideInfo(): SessionMaybeProvideInfo {
-    const hooks: Record<string, undefined> = {}
-    const props: Record<string, undefined> = {}
-    for (const descriptor of this.providers) {
-      for (const name of descriptor.hooks ?? []) {
-        if (Object.hasOwn(hooks, name)) throw new Error(`sessions.provide: duplicate hook "${name}"`)
-        hooks[name] = undefined
-      }
-      for (const name of descriptor.props ?? []) {
-        if (Object.hasOwn(props, name)) throw new Error(`sessions.provide: duplicate prop "${name}"`)
-        props[name] = undefined
-      }
-    }
-    return { sessionId: undefined, hooks, props } // no projections face: every key reads absent without a session
-  }
-
-  /** Materialize the standard-props bundle for one session (fails loud on duplicate member names). */
-  private materializeProvideInfo(binding: SessionBinding): SessionProvideInfo {
-    const hooks: Record<string, HostObservable<unknown>> = {}
-    const props: Record<string, unknown> = {}
-    for (const descriptor of this.providers) {
-      const contribution = descriptor.resolve(binding)
-      const contributedHooks = contribution.hooks ?? {}
-      const contributedProps = contribution.props ?? {}
-      for (const name of Object.keys(contributedHooks)) {
-        if (!(descriptor.hooks ?? []).includes(name)) {
-          throw new Error(`sessions.provide: undeclared hook "${name}"`)
-        }
-      }
-      for (const name of Object.keys(contributedProps)) {
-        if (!(descriptor.props ?? []).includes(name)) {
-          throw new Error(`sessions.provide: undeclared prop "${name}"`)
-        }
-      }
-      for (const name of descriptor.hooks ?? []) {
-        const source = contributedHooks[name]
-        if (source === undefined) throw new Error(`sessions.provide: missing hook "${name}"`)
-        if (Object.hasOwn(hooks, name)) throw new Error(`sessions.provide: duplicate hook "${name}"`)
-        hooks[name] = source
-      }
-      for (const name of descriptor.props ?? []) {
-        if (!Object.hasOwn(contributedProps, name)) throw new Error(`sessions.provide: missing prop "${name}"`)
-        if (Object.hasOwn(props, name)) throw new Error(`sessions.provide: duplicate prop "${name}"`)
-        props[name] = contributedProps[name]
-      }
-    }
-    return {
-      sessionId: binding.sessionId,
-      hooks,
-      props,
-      // The useProjection seat: key-addressed bare value faces off the
-      // session's projection store (open key space — never a static roster member).
-      projections: { faceOf: key => binding.session.projections.faceOf(key) },
-    }
+    // scopes before later plugins register) — the channel rebuilds their
+    // bundles through the host hooks so every provider lands by first render.
+    return this.provideChannel.provide(descriptor)
   }
 
   /**
@@ -439,9 +338,9 @@ export class SessionsService {
    * `agent.session`). Same service-method seam as
    * {@link SessionsService.scopeOf}.
    * @param ctx - an Agent-scoped context.
-   * @returns the Session, or undefined when the ctx is untagged or its scope was pruned.
+   * @returns the session face, or undefined when the ctx is untagged or its scope was pruned.
    */
-  sessionOf(ctx: Context): Session | undefined {
+  sessionOf(ctx: Context): SessionFace | undefined {
     const id = scopeTagOf(ctx)
     if (id === undefined) return undefined
     return this.scopes.get(id)?.binding.session
@@ -473,7 +372,7 @@ export class SessionsService {
    * return the static no-session projection rather than removing hook props.
    */
   private maybeProvideInfo(id: string | undefined): SessionMaybeProvideInfo {
-    return (id === undefined ? undefined : this.provideInfo(id)) ?? this.maybeInfo
+    return (id === undefined ? undefined : this.provideInfo(id)) ?? this.provideChannel.maybeInfo
   }
 
   /**
@@ -497,7 +396,7 @@ export class SessionsService {
      * validates and the projection masks absent selections), so resolve
      * cannot miss; kept so a future current writer cannot crash the notify. */
     if (record !== undefined) {
-      void record.binding.session.open()
+      void record.session.open()
     }
   }
 
@@ -540,8 +439,9 @@ export class SessionsService {
       fiber,
       ctx,
       binding,
+      session,
       // Sources are bare observables; React binds selector hooks at its own seam.
-      provideInfo: this.materializeProvideInfo(binding),
+      provideInfo: this.provideChannel.materializeInfo(binding),
     }
     this.scopes.set(id, record)
     return record
@@ -608,7 +508,7 @@ export class SessionsService {
     void record.fiber.dispose()
     // Release the Session's dispatch point with the scope it belongs to (a
     // surviving instance — the live Intent — rebinds when resolve re-mints).
-    record.binding.session.unbindScope()
+    record.session.unbindScope()
     // Optional lookup: slots and sessions are sibling services with no
     // declared dependency; a slots-less boot (object-layer tests) skips.
     this.rootCtx.get('slots')?.pruneStoreScope(id)

packages/client/runtime/src/client/sessions/session.ts

@@ -10,7 +10,7 @@ import type {
 // Value import from the inline-safe wire layer (not the connection plugin):
 // plugin-to-plugin value imports are a bundle purity error.
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
-import type { ObservableSnapshot } from '../contract/store.ts'
+import type { SessionFace } from '../contract/session.ts'
 import type {
   CodeSubCall, ComposerPhase, ConversationNode, ConversationSnapshot, OpenState,
   PromptError, QueuedMessage, RunningToolCall,
@@ -67,9 +67,11 @@ function queuePreviewOf(content: readonly ContentBlock[]): string {
 
 /**
  * Owns a session's event window, derived conversation state, and observable
- * snapshot. React bindings remain outside this data layer.
+ * snapshot. React bindings remain outside this data layer. Features see only
+ * the {@link SessionFace} slice (ISession verbs + the snapshot source); the
+ * remaining public members are manager/runtime entry points.
  */
-export class Session implements ObservableSnapshot<ConversationSnapshot> {
+export class Session implements SessionFace {
   // ---- Window and derived state (all private; the snapshot is the only read surface) ----
   private events: SessionEvent[] = []
   /** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).

packages/client/runtime/src/client/workspaces/service.ts

@@ -6,7 +6,8 @@ import type {
 } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotStore } from '../contract/store.ts'
 import { createSnapshotStore } from '../contract/store.ts'
-import type { SessionsService } from '../sessions/service.ts'
+import type { SessionsPort, SessionsPortList } from '../contract/sessions-port.ts'
+import type { IWorkspaces } from '../contract/workspaces.ts'
 import { WorkspaceManager, type WorkspaceListPhase } from './manager.ts'
 
 /** Workspace list plus the two-baseline readiness and default-target projection. */
@@ -30,7 +31,7 @@ export class WorkspaceCreateError extends Error {
 }
 
 /** Real Workspace object layer and Host actions. */
-export class WorkspacesService {
+export class WorkspacesService implements IWorkspaces {
   /** UI-facing immutable projection; the manager remains wire truth. */
   readonly list: SnapshotStore<WorkspaceListState>
   /** Workspace baseline and frame owner. */
@@ -43,9 +44,9 @@ export class WorkspacesService {
   /**
    * @param ctx - client root context.
    * @param api - shared wire client.
-   * @param sessions - lower-level Session service used for recency and blank-session reuse.
+   * @param sessions - cross-domain sessions face used for recency and blank-session reuse.
    */
-  constructor(ctx: Context, private readonly api: IApiClient, private readonly sessions: SessionsService) {
+  constructor(ctx: Context, private readonly api: IApiClient, private readonly sessions: SessionsPort) {
     this.manager = new WorkspaceManager(api)
     this.list = createSnapshotStore<WorkspaceListState>({
       items: [], state: 'idle', phase: 'pending', error: null,
@@ -271,7 +272,7 @@ export class WorkspacesService {
 /** Stable tie-breaking follows Host Workspace order. */
 function recentWorkspace(
   workspaces: readonly WorkspaceView[],
-  sessions: ReturnType<SessionsService['list']['getSnapshot']>['byId'],
+  sessions: SessionsPortList['byId'],
 ): WorkspaceId | undefined {
   let selected: WorkspaceId | undefined
   let selectedTime = Number.NEGATIVE_INFINITY

packages/client/runtime/tests/manager.spec.ts

@@ -160,6 +160,28 @@ describe('list lifecycle', () => {
     expect(manager.getListSnapshot().items.find(item => item.sessionId === S1)?.title).toBeUndefined()
   })
 
+  it('seeds cold titles from the list rows\' projections block under higher-seq-wins', async () => {
+    const api = new FakeApiClient()
+    const manager = new SessionManager(api)
+    // A push frame landed before the list (S2's title is newer than the block's cut).
+    manager.handleMuxEnvelope({
+      rpcId: 'push-newer' as never,
+      payload: { type: 'session/projection', sessionId: S2, key: 'title', value: 'Pushed', seq: 9 } as never,
+    })
+    api.onList = () => Promise.resolve(ok({
+      items: [
+        { ...summary(S1), projections: { asOfSeq: 4, values: { title: 'Cold cached' } } },
+        { ...summary(S2, { updatedAt: 200 }), projections: { asOfSeq: 5, values: { title: 'List stale' } } },
+      ] as never[],
+    }))
+    await manager.refreshList()
+    const items = manager.getListSnapshot().items
+    // Cold row: title surfaces straight from the list block — no open, no history.
+    expect(items.find(item => item.sessionId === S1)?.title).toBe('Cold cached')
+    // The stale list block (seq 5) cannot overwrite the newer push frame (seq 9).
+    expect(items.find(item => item.sessionId === S2)?.title).toBe('Pushed')
+  })
+
   it('drops a projection row beyond the subscription baseline before accepting its durable replay', async () => {
     const api = new FakeApiClient()
     api.onList = () => Promise.resolve(ok({ items: [summary(S1)] as never[] }))

packages/client/test-runtime/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/test-runtime/README.md
+README.md: 883d71224139dc409229fdfb35362d040e810cc7
+README.zh.md: a3daf112940b03b585d44bc5fd1317e43ebd35fe

packages/client/test-runtime/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-client-test-runtime
+
+English | [中文](README.zh.md)
+
+jsdom slot test runtime for client feature specs: a real Cordis `Context`, the production `SlotsService` and web-react renderer, assembled around typed session/workspace doubles. Feature suites exercise declaration, registration, scope, store, inject, rendering, updates, and disposal without hand-building the machinery per suite — and without a second implementation of any production logic.
+
+The doubles implement the same outward faces features receive through ctx (`TestSessions implements ISessions`, `TestWorkspaces implements IWorkspaces`; each fixture session is a `FixtureSession implements SessionFace`), so a production face change breaks the bench at compile time instead of silently drifting. Provide-bundle materialization runs the production `SessionProvideChannel` — the one implementation shared with `SessionsService`. Fixtures feed plain data: list rows, conversation snapshots (immer-patched via `updateSnapshot`), projection values, and `ISession`-typed behavior stubs that fail loud when a spec calls an unstubbed verb. The typed `provide()` constrains fakes for declared service names to `Partial` of that service's outward face.
+
+Local DOM snapshots: `declare(children)` registers an auto frame whose per-key `<div data-slot>` wrappers are snapshot roots; `renderSlot(key, owner)` returns the slot-local view (container, scoped Testing Library queries, in-place `update(owner)`); a registered snapshot serializer folds CSS-module class hashes (`_frame_a1b2c3` → `frame`) to keep `.snap` files structural and collapses `<svg>` internals to a `data-content` fingerprint. Suites needing a custom page frame use `root.declare(children, Frame)` instead; `mount(plugin)` runs a real fiber with fail-loud service prechecks, and `dispose()` tears down views, feature fibers, minted scopes, and persisted store state on one axis.
+
+Not part of the product plugin graph (no `dshClient`); feature packages depend on it in `devDependencies` only.
+
+## Model Experience
+
+None, as this package is browser-side test infrastructure; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Consumed through repository source aliases only.** Specs resolve the package through tsconfig `paths` to `src`; the built `lib/` artifact re-exports `@deepseek-ai/dsh-client-runtime/client`, whose bundle is a browser loader script with no Node ESM exports, so `lib/index.js` is not importable under plain Node. Acceptable while every consumer is an in-repo Vitest suite; a Node-compatible runtime entry is deferred until an out-of-repo consumer exists.
+- **Conversation snapshots are fixture data, not replayed history.** `updateSnapshot` writes the snapshot store directly; the wire-to-snapshot computation stays covered by the runtime package's own tests and the replay e2e. A fixture can therefore express states the production fold would never produce.

packages/client/test-runtime/README.zh.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-client-test-runtime
+
+[English](README.md) | 中文
+
+面向 client feature 测试的 jsdom slot 测试运行时：真实 Cordis `Context`、生产 `SlotsService` 与 web-react 渲染器，围绕带类型的 session/workspace 测试替身组装。feature 套件无需逐套件手搭机器即可测遍声明、注册、scope、store、inject、渲染、更新与销毁——且不存在任何生产逻辑的第二份实现。
+
+替身实现的正是 feature 经 ctx 拿到的对外面（`TestSessions implements ISessions`、`TestWorkspaces implements IWorkspaces`；每个 fixture session 是 `FixtureSession implements SessionFace`），生产面一旦改形，测试台在编译期即断，而非静默漂移。provide bundle 材料化直接运行生产 `SessionProvideChannel`——与 `SessionsService` 共用同一份实现。fixture 灌入的是普通数据：列表行、会话快照（经 `updateSnapshot` 以 immer 补丁改写）、projection 值，以及按 `ISession` 取型的行为桩——spec 调用未打桩的动词时报错自明。带类型的 `provide()` 将已声明服务名的 fake 约束为该服务对外面的 `Partial` 子集。
+
+局部 DOM 快照：`declare(children)` 注册自动 frame，逐 key 的 `<div data-slot>` 包裹层即快照根；`renderSlot(key, owner)` 返回该 slot 的局部视图（container、限定范围的 Testing Library 查询、原位 `update(owner)`）；注册的快照序列化器把 CSS-module 哈希类名折回语义名（`_frame_a1b2c3` → `frame`）保持 `.snap` 只含结构，并把 `<svg>` 内部折叠为 `data-content` 指纹。需要自定义页面 frame 的套件改用 `root.declare(children, Frame)`；`mount(plugin)` 在真实 fiber 上运行并对缺失服务先行报错；`dispose()` 沿单一轴拆除视图、feature fiber、已铸 scope 与持久化 store 状态。
+
+不属于产品插件图（无 `dshClient`）；feature 包仅以 `devDependencies` 依赖之。
+
+## Model Experience
+
+无；本包是浏览器侧测试基础设施，无一物到达模型请求。
+
+#### KV Cache effect
+
+无；本包既不组装也不发送 provider 请求。
+
+## Known Limitations and Deferred Work
+
+- **仅可经仓内源码别名消费。** spec 通过 tsconfig `paths` 解析到 `src`；构建产物 `lib/` 再导出 `@deepseek-ai/dsh-client-runtime/client`，而该 bundle 是无 Node ESM 导出的浏览器 loader 脚本，故 `lib/index.js` 在纯 Node 下不可导入。当前所有消费方都是仓内 Vitest 套件，可接受；Node 兼容的运行时入口待出现仓外消费方再补。
+- **会话快照是 fixture 数据，不是重放历史。** `updateSnapshot` 直写快照 store；wire 到快照的运算仍由 runtime 包自身测试与 replay e2e 把守。因此 fixture 可以表达生产折叠永不产出的状态。

packages/client/test-runtime/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@deepseek-ai/dsh-client-test-runtime",
+  "description": "jsdom slot test runtime: real Cordis Context + SlotsService + web-react renderer with test-owned session/workspace doubles for feature specs",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "vitest": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
+    "@deepseek-ai/dsh-client-web-react": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ]
+}

packages/client/test-runtime/src/fixtures.ts

@@ -0,0 +1,82 @@
+/** Session/workspace fixture shapes and snapshot defaults for the test runtime. */
+import type {
+  ConversationSnapshot, ISession, SessionId, SessionSummary, WorkspaceListState,
+} from '@deepseek-ai/dsh-client-runtime/client'
+
+/**
+ * Fixture overrides for the session behavior face: any subset of the
+ * production ISession verbs (typed against it, so a face change surfaces
+ * here at compile time), plus extra members feature-specific casts consume.
+ * The open Record tail means a misnamed EXTRA member is not caught by the
+ * compiler (it grafts as dead weight); the ISession verbs stay safe — a
+ * misnamed verb leaves the fail-loud stub in place, which names itself at
+ * the first call.
+ */
+export type SessionBehaviorOverrides = Partial<ISession> & Record<string, unknown>
+
+/**
+ * act-wrapped mutation runner shared by every runtime object: public mutators
+ * funnel through it so tests never handle SlotCore microtask batching or
+ * React act themselves.
+ */
+export type Stabilizer = (fn: () => void | Promise<void>) => Promise<void>
+
+/**
+ * Session fixture accepted by {@link TestSessions.add}: identity plus optional
+ * snapshot/list-row overrides and the session behavior face the feature under
+ * test actually calls (kept open — the runtime never fakes methods a test did
+ * not supply, so an unstubbed call fails loud at the call site).
+ */
+export interface SessionFixture {
+  id: string
+  /** Overrides merged over {@link conversationSnapshot} (sessionId comes from `id`). */
+  snapshot?: Partial<Omit<ConversationSnapshot, 'sessionId'>>
+  /** List-row overrides merged over the defaults derived from `id`. */
+  summary?: Partial<Omit<SessionSummary, 'id'>>
+  /** Session behavior face: exactly the methods the feature under test calls (ISession subset + extras). */
+  session?: SessionBehaviorOverrides
+}
+
+/**
+ * A complete quiescent conversation snapshot (open window, no traffic).
+ * @param sessionId - owning session id.
+ * @returns the snapshot; spread fixture overrides on top.
+ */
+export function conversationSnapshot(sessionId: SessionId): ConversationSnapshot {
+  return {
+    sessionId,
+    nodes: [],
+    foldDegraded: false,
+    partial: null,
+    runningCalls: [],
+    codeDispatches: new Map(),
+    pending: [],
+    queue: [],
+    running: false,
+    composerPhase: 'active',
+    removed: false,
+    openState: 'open',
+    openError: null,
+    hasMore: false,
+    loadingOlder: false,
+    promptError: null,
+    blank: false,
+    lastAgentError: null,
+  }
+}
+
+/**
+ * A ready workspace list with no workspaces (the shape WorkspacesService
+ * projects after both baselines land).
+ * @returns the initial state of the test workspaces store.
+ */
+export function workspaceListState(): WorkspaceListState {
+  return {
+    items: [],
+    state: 'idle',
+    phase: 'ready',
+    error: null,
+    baselinesReady: true,
+    recentWorkspaceId: undefined,
+  }
+}

packages/client/test-runtime/src/index.ts

@@ -0,0 +1,372 @@
+/**
+ * jsdom slot test runtime: a real small runtime — Cordis `Context`, the
+ * runtime `SlotsService`, and the web-react renderer — assembled around
+ * test-owned session/workspace doubles, so feature specs exercise
+ * declaration, registration, scope, store, inject, rendering, updates, and
+ * disposal without hand-building the machinery per suite.
+ *
+ * Not part of the product plugin graph (no `dshClient`); feature packages
+ * depend on it in devDependencies only. It copies no SlotCore/renderer/store
+ * machinery — everything mounts the production implementations.
+ * @module @deepseek-ai/dsh-client-test-runtime
+ */
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents --
+ * `keyof SlotMap & string` is the declare-merge key pattern (see ui-slots):
+ * this compilation unit sees only the runtime's 'root' row, but consumer
+ * programs merge their own keys in; the rule fires on the narrow-map view. */
+import { Context, Inject } from 'cordis'
+import type { Fiber, Plugin } from 'cordis'
+import { createElement, Fragment, useSyncExternalStore } from 'react'
+import type { ReactNode } from 'react'
+import { act, render, within } from '@testing-library/react'
+import type { RenderResult } from '@testing-library/react'
+import type { queries } from '@testing-library/dom'
+import type { BoundFunctions } from '@testing-library/dom'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
+import type {
+  ChildrenDecl, ComposedProps, OwnerOf, SlotComponent, SlotMap, SlotRendererHost, StoreInstanceLike,
+} from '@deepseek-ai/dsh-client-ui-slots'
+import { registerDomSnapshotSerializer } from './snapshot.ts'
+import { TestSessions } from './sessions.ts'
+import { TestWorkspaces } from './workspaces.ts'
+import type { Stabilizer } from './fixtures.ts'
+
+export { domSnapshotSerializer, registerDomSnapshotSerializer } from './snapshot.ts'
+export { FixtureSession, TestSessions } from './sessions.ts'
+export { TestWorkspaces } from './workspaces.ts'
+export { conversationSnapshot, workspaceListState } from './fixtures.ts'
+export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fixtures.ts'
+
+/** Erased register face for the internal root call (the public declare seam holds the typing). */
+type ErasedRegister = (options: object, component: unknown) => () => void
+
+/**
+ * One rendered slot's local view, from {@link SlotTestRuntime.renderSlot}:
+ * the `data-slot` wrapper is the snapshot root (`expect(view.container)
+ * .toMatchSnapshot()` captures exactly this slot's output), Testing Library
+ * queries are bound inside it, and `update` re-renders with new owner props.
+ */
+export interface SlotView<K extends keyof SlotMap & string> {
+  /** The `<div data-slot="<key>">` wrapper around the slot's rendered output. */
+  readonly container: HTMLElement
+  /** Testing Library queries scoped to {@link SlotView.container}. */
+  readonly view: BoundFunctions<typeof queries>
+  /**
+   * Replace the owner props and flush the re-render (the render-site update:
+   * in production the owner recomputes the share and React re-renders).
+   * @param owner - the next owner props share.
+   */
+  update(owner: OwnerOf<K>): void
+}
+
+/**
+ * Mounted feature plugin handle: the live fiber plus an act-wrapped,
+ * idempotent dispose (unload cascade: entries, declared child slots, store
+ * instances, and provided services all fall together).
+ */
+export interface FeatureHandle {
+  /** The plugin's live Cordis fiber (state assertions, escape hatch). */
+  readonly fiber: Fiber
+  /**
+   * Dispose the plugin fiber inside React act; repeated calls no-op.
+   * @returns completion of the unload cascade.
+   */
+  dispose(): Promise<void>
+}
+
+/**
+ * Owner-props cell behind the auto frame: one external store the frame
+ * subscribes to, so {@link SlotTestRuntime.renderSlot} and
+ * {@link SlotView.update} drive React through the standard uSES seam.
+ */
+class OwnerPropsCell {
+  private readonly owners = new Map<string, object>()
+  private readonly listeners = new Set<() => void>()
+  private version = 0
+
+  /** Snapshot version for uSES pairing (bumped on every set). */
+  readonly getVersion = (): number => this.version
+
+  /**
+   * Subscribe to owner-props changes.
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  readonly subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn)
+    return () => { this.listeners.delete(fn) }
+  }
+
+  /**
+   * Install or replace one key's owner props and notify (synchronous; the
+   * caller wraps in act).
+   * @param key - slot key.
+   * @param owner - owner props share.
+   */
+  set(key: string, owner: object): void {
+    this.owners.set(key, owner)
+    this.version += 1
+    for (const fn of [...this.listeners]) fn()
+  }
+
+  /** Keys with supplied owner props, in first-supply order. */
+  entries(): readonly (readonly [string, object])[] {
+    return [...this.owners.entries()]
+  }
+}
+
+/**
+ * The test-owned 'root' occupant: declares the child slots a suite needs
+ * through the REAL `slots.register`, with a caller-supplied minimal frame —
+ * the runtime never guesses a feature's page structure.
+ */
+export class TestRoot {
+  private disposeEntry: (() => void) | undefined
+
+  /**
+   * @param slots - the runtime SlotsService.
+   * @param stabilize - the owning runtime's act wrapper.
+   */
+  constructor(private readonly slots: SlotsService, private readonly stabilize: Stabilizer) {}
+
+  /**
+   * Register the root frame, declaring (and thereby claiming) the child
+   * slots. One declaration per runtime — a second call fails loud in the
+   * core ('root' is a single slot).
+   * @param children - child-slot declaration table (declaration + render authorization + runtime spec).
+   * @param frame - minimal frame component; its props derive from the declared keys (composed-props contract).
+   * @returns completion of the act-wrapped registration.
+   */
+  async declare<const D extends ChildrenDecl>(
+    children: D,
+    frame: SlotComponent<ComposedProps<'root', keyof NoInfer<D> & keyof SlotMap & string, undefined, object>>,
+  ): Promise<void> {
+    await this.stabilize(() => {
+      // Erased hop (same pattern as SlotsService's own implementation arm);
+      // the declare signature above is the typed seam.
+      this.disposeEntry = (this.slots.register as unknown as ErasedRegister)({ name: 'root', children }, frame)
+    })
+  }
+
+  /** Remove the root registration and collapse its declarations (runtime dispose path). */
+  release(): void {
+    this.disposeEntry?.()
+    this.disposeEntry = undefined
+  }
+}
+
+/**
+ * The assembled test runtime. Obtain via {@link SlotTestRuntime.create};
+ * dispose with {@link SlotTestRuntime.dispose} (afterEach). Public mutators
+ * are act-wrapped throughout — tests never handle SlotCore microtask
+ * batching or React act themselves.
+ */
+export class SlotTestRuntime {
+  /** The runtime's Cordis root (escape hatch: extra services via `ctx.provide`, raw `ctx.plugin` mounts). */
+  readonly ctx: Context
+  /** The production SlotsService mounted on {@link SlotTestRuntime.ctx}. */
+  readonly slots: SlotsService
+  /** The test-owned 'root' occupant. */
+  readonly root: TestRoot
+  /** Sessions double (list/current observable, cells, scopes, behavior faces). */
+  readonly sessions: TestSessions
+  /** Workspaces double (list observable, recorded intent actions). */
+  readonly workspaces: TestWorkspaces
+
+  private readonly stabilizer: Stabilizer = async (fn) => {
+    await act(async () => { await fn() })
+  }
+
+  private host: SlotRendererHost | undefined
+  private readonly views: RenderResult[] = []
+  private readonly handles: FeatureHandle[] = []
+  private disposed = false
+  /** Auto-frame state ({@link SlotTestRuntime.declare} / {@link SlotTestRuntime.renderSlot}). */
+  private readonly ownerCell = new OwnerPropsCell()
+  private readonly autoDeclared = new Set<string>()
+  private autoRootView: RenderResult | undefined
+
+  private constructor(ctx: Context, slots: SlotsService) {
+    this.ctx = ctx
+    this.slots = slots
+    this.root = new TestRoot(slots, this.stabilizer)
+    this.sessions = new TestSessions(this.stabilizer, ctx)
+    this.workspaces = new TestWorkspaces(this.stabilizer)
+    ctx.provide('sessions', this.sessions)
+    ctx.provide('workspaces', this.workspaces)
+    // Capturing install: the production renderer does the rendering; the
+    // wrapper only takes the host face for storeOf (no machinery copied).
+    const renderer = createSlotRenderer()
+    slots.install({
+      renderRoot: (host, ownerProps) => {
+        this.host = host
+        return renderer.renderRoot(host, ownerProps)
+      },
+    })
+  }
+
+  /**
+   * Assemble a runtime: real Context, mounted SlotsService, installed
+   * renderer, and the session/workspace doubles provided as services.
+   * @returns the ready runtime.
+   */
+  static async create(): Promise<SlotTestRuntime> {
+    registerDomSnapshotSerializer()
+    const ctx = new Context()
+    const fiber = ctx.plugin(SlotsService)
+    await fiber.await()
+    return new SlotTestRuntime(ctx, ctx.get('slots') as SlotsService)
+  }
+
+  /**
+   * Provide an extra service the feature under test injects (e.g. a layout
+   * fake). Sugar over `ctx.provide`, typed against the Context declaration
+   * merge: for a declared service name the fake must be a subset of that
+   * service's outward face (Partial — supply only what the feature calls),
+   * so a production face change breaks the fake at compile time. Undeclared
+   * names stay unchecked (ad-hoc test services).
+   * @param name - service name.
+   * @param value - service implementation (test double).
+   */
+  provide<K extends string>(name: K, value: K extends keyof Context ? Partial<Context[K]> : unknown): void {
+    this.ctx.provide(name, value)
+  }
+
+  /**
+   * Mount a feature plugin on a real fiber. Required services are prechecked
+   * so a missing provider fails loud instead of suspending the fiber forever
+   * (deliberate load-order suspension tests use `ctx.plugin` directly).
+   * @param plugin - plugin value (function, class, or `{ inject, apply }` object).
+   * @returns handle owning the fiber's explicit disposal.
+   */
+  async mount(plugin: Plugin): Promise<FeatureHandle> {
+    const required = Object.keys(Inject.resolve((plugin as { inject?: Inject }).inject))
+    const missing = required.filter(name => this.ctx.get(name) === undefined)
+    if (missing.length > 0) {
+      throw new Error(`mount would suspend: missing service(s) ${missing.join(', ')} — provide() them first`)
+    }
+    const fiber = this.ctx.plugin(plugin)
+    await this.stabilizer(async () => {
+      await fiber.await()
+    })
+    let disposed = false
+    const handle: FeatureHandle = {
+      fiber,
+      dispose: async () => {
+        if (disposed) return
+        disposed = true
+        await this.stabilizer(() => fiber.dispose())
+      },
+    }
+    this.handles.push(handle)
+    return handle
+  }
+
+  /**
+   * Render the root slot tree through the ctx-level entry (the shell's own
+   * seam): `ctx.slots.renderSlot('root', {})` under Testing Library.
+   * @returns the Testing Library view.
+   */
+  renderRoot(): RenderResult {
+    const view = render(createElement(Fragment, null, this.slots.renderSlot('root', {})))
+    this.views.push(view)
+    return view
+  }
+
+  /**
+   * Declare child slots under an auto-generated root frame — the single-slot
+   * mounting path for local DOM snapshots. Each key later supplied through
+   * {@link SlotTestRuntime.renderSlot} renders inside its own
+   * `<div data-slot="<key>">` wrapper (the snapshot root). Mutually exclusive
+   * with {@link TestRoot.declare} ('root' is a single slot); one call per
+   * runtime.
+   * @param children - child-slot declaration table (same contract as TestRoot.declare).
+   * @returns completion of the act-wrapped registration.
+   */
+  async declare(children: ChildrenDecl): Promise<void> {
+    for (const key of Object.keys(children)) this.autoDeclared.add(key)
+    const cell = this.ownerCell
+    const AutoFrame = (props: { renderSlot: (key: string, owner: object) => ReactNode }) => {
+      useSyncExternalStore(cell.subscribe, cell.getVersion)
+      return createElement(Fragment, null, cell.entries().map(([key, owner]) =>
+        createElement('div', { 'data-slot': key, key }, props.renderSlot(key, owner))))
+    }
+    await this.root.declare(children as never, AutoFrame as never)
+  }
+
+  /**
+   * Render one declared slot with its owner props and return the local view.
+   * The whole root tree mounts through the production assembly path
+   * (renderer, scope providers, store axis); only this key's output lands in
+   * the returned container. Call again with another key to view a sibling
+   * slot of the same tree.
+   * @param key - a key declared through {@link SlotTestRuntime.declare}.
+   * @param owner - owner props share for the render site.
+   * @returns the slot-local view (snapshot container, scoped queries, owner updates).
+   */
+  renderSlot<K extends keyof SlotMap & string>(key: K, owner: OwnerOf<K>): SlotView<K> {
+    if (!this.autoDeclared.has(key)) {
+      throw new Error(`renderSlot('${key}') without declare() — declare the key first (or use root.declare for a custom frame)`)
+    }
+    const install = (next: object): void => {
+      // Synchronous cell write inside act: the frame re-renders through uSES.
+      act(() => {
+        this.ownerCell.set(key, next)
+      })
+    }
+    install(owner)
+    this.autoRootView ??= this.renderRoot()
+    const container = this.autoRootView.container.querySelector(`[data-slot="${key}"]`)
+    if (!(container instanceof HTMLElement)) {
+      throw new Error(`renderSlot('${key}'): the auto frame rendered no wrapper — was the runtime already disposed?`)
+    }
+    return { container, view: within(container), update: install }
+  }
+
+  /**
+   * Resolve the store instance the renderer would hand a slot's component
+   * (identity assertions, action-driven writes). Requires a prior
+   * {@link SlotTestRuntime.renderRoot} — the host face exists only inside the
+   * installed renderer, exactly as in production.
+   * @param key - slot key whose first entry declares the store.
+   * @param scopeKey - session id for session-scope slots; omit for root scope.
+   * @returns the live store instance.
+   */
+  storeOf(key: keyof SlotMap & string, scopeKey?: string): StoreInstanceLike {
+    if (this.host === undefined) {
+      throw new Error('storeOf before renderRoot() — the host face exists only inside the installed renderer')
+    }
+    const entry = this.host.entriesOf(key)[0]
+    if (entry === undefined) throw new Error(`storeOf('${key}'): no registration on the ledger`)
+    const instance = this.host.storeOf(entry, scopeKey)
+    if (instance === undefined) throw new Error(`storeOf('${key}'): the entry declares no store`)
+    return instance
+  }
+
+  /**
+   * Flush pending ledger/store notifications inside act — for mutations made
+   * outside the runtime's own methods (e.g. a direct `slots.register`).
+   * @returns completion of the act pass.
+   */
+  async flush(): Promise<void> {
+    await this.stabilizer(() => {})
+  }
+
+  /**
+   * Tear down: unmount React trees first, then dispose feature fibers, the
+   * root registration, minted session scopes, and persisted test state.
+   * Idempotent.
+   * @returns completion of the teardown.
+   */
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+    this.disposed = true
+    this.autoRootView = undefined
+    for (const view of this.views.splice(0)) view.unmount()
+    for (const handle of this.handles.splice(0)) await handle.dispose()
+    this.root.release()
+    await this.sessions.disposeScopes()
+    localStorage.clear()
+  }
+}

packages/client/test-runtime/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-test-runtime`.
+ * @module @deepseek-ai/dsh-client-test-runtime/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-client-test-runtime'
+
+/** Cordis companion plugin name. */
+export const name = 'client-test-runtime-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this test-support package owns no production event
+ * stream or mutable data — it assembles the runtime SlotsService and renderer
+ * (whose packages own their invariants) around test doubles; its own behavior
+ * is exercised by its package tests.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/client/test-runtime/src/sessions.ts

@@ -0,0 +1,390 @@
+/** Test-owned sessions face: the SlotsService host contract over declarative fixtures. */
+import type { Context } from 'cordis'
+import { createScope, scopeOf, SessionProvideChannel } from '@deepseek-ai/dsh-client-runtime/client'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ConversationSnapshot, ISessions, ObservableSnapshot, ProjectionsFace, SessionFace, SessionId,
+  SessionListState, SessionProvideDescriptor, SessionSummary, SnapshotStore,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { HostObservable, SessionMaybeProvideInfo, SessionProvideInfo } from '@deepseek-ai/dsh-client-ui-slots'
+import { conversationSnapshot } from './fixtures.ts'
+import type { SessionFixture, Stabilizer } from './fixtures.ts'
+
+/**
+ * The fixture-backed session face: conversation reads delegate to the
+ * fixture's snapshot store; ISession verbs are fail-loud stubs unless the
+ * fixture supplies them (the runtime never fakes behavior a test did not
+ * declare — an unstubbed call names itself instead of half-working). Extra
+ * fixture methods are grafted verbatim for feature-side casts.
+ */
+export class FixtureSession implements SessionFace {
+  /**
+   * The useProjection seat: identity-stable per-key faces over the fixture's
+   * projection values (set via {@link TestSessions.setProjection}).
+   */
+  readonly projections: ProjectionsFace & { set(key: string, value: unknown): void }
+
+  /**
+   * @param sessionId - host identity (branded view of the fixture id).
+   * @param store - conversation snapshot store (updateSnapshot writes it).
+   * @param overrides - fixture-declared behavior face, grafted over the stubs.
+   */
+  constructor(
+    readonly sessionId: SessionId,
+    private readonly store: SnapshotStore<ConversationSnapshot>,
+    overrides: Record<string, unknown>,
+  ) {
+    const values = new Map<string, unknown>()
+    const listeners = new Map<string, Set<() => void>>()
+    const faces = new Map<string, ObservableSnapshot<unknown>>()
+    this.projections = {
+      faceOf: (key: string) => {
+        let face = faces.get(key)
+        if (face === undefined) {
+          face = {
+            getSnapshot: () => values.get(key),
+            subscribe: (fn: () => void) => {
+              const set = listeners.get(key) ?? new Set()
+              set.add(fn)
+              listeners.set(key, set)
+              return () => { set.delete(fn) }
+            },
+          }
+          faces.set(key, face)
+        }
+        return face
+      },
+      set: (key: string, value: unknown) => {
+        values.set(key, value)
+        for (const fn of [...(listeners.get(key) ?? [])]) fn()
+      },
+    }
+    Object.assign(this, overrides)
+  }
+
+  /** @returns the fixture conversation snapshot (useSession read side). */
+  getSnapshot(): ConversationSnapshot {
+    return this.store.getSnapshot()
+  }
+
+  /**
+   * Subscribe to fixture snapshot changes.
+   * @param fn - change callback.
+   * @returns unsubscribe.
+   */
+  subscribe(fn: () => void): () => void {
+    return this.store.subscribe(fn)
+  }
+
+  /**
+   * Fail-loud stub; supply `prompt` on the fixture's session face to exercise it.
+   * @returns never — always throws.
+   */
+  prompt(): never {
+    throw new Error(`test session "${this.sessionId}": prompt is not stubbed — supply it on the fixture's session face`)
+  }
+
+  /**
+   * Fail-loud stub; supply `cancel` on the fixture's session face to exercise it.
+   * @returns never — always throws.
+   */
+  cancel(): never {
+    throw new Error(`test session "${this.sessionId}": cancel is not stubbed — supply it on the fixture's session face`)
+  }
+
+  /**
+   * Fail-loud stub; supply `loadOlder` on the fixture's session face to exercise it.
+   * @returns never — always throws.
+   */
+  loadOlder(): never {
+    throw new Error(`test session "${this.sessionId}": loadOlder is not stubbed — supply it on the fixture's session face`)
+  }
+}
+
+/** One live test session: fixture-derived stores plus its minted scope state. */
+interface SessionRecord {
+  summary: SessionSummary
+  snapshot: SnapshotStore<ConversationSnapshot>
+  session: FixtureSession
+  scope: Context | undefined
+  scopeFiber: { dispose(): Promise<void> } | undefined
+  /** Materialized standard-props bundle (identity-stable per session; invalidated on roster change). */
+  provideInfo: SessionProvideInfo | undefined
+}
+
+/** Test binding shape handed to provider resolvers and feature injects (a SessionBinding whose session is the fixture face). */
+export interface TestSessionBinding {
+  readonly sessionId: SessionId
+  readonly session: FixtureSession
+  readonly ctx: Context
+}
+
+/**
+ * Sessions test double behind the renderer host and feature injects: owns the
+ * list/current observable, the standard-props provide channel (the runtime's
+ * `useSession` contribution included), scope minting through the production
+ * `createScope`, and the session behavior face supplied per fixture.
+ *
+ * Implements the same ISessions face features receive as `ctx.sessions`, so
+ * a production face change breaks this double at compile time; the extra
+ * members (add/updateSnapshot/setCurrent/remove/behavior/calls and the
+ * legacy provideInfo/maybeProvideInfo lookups) are bench-only surface.
+ */
+export class TestSessions implements ISessions {
+  /** The useSessions standard feed (list rows + current selection). */
+  readonly list: SnapshotStore<SessionListState>
+  /**
+   * Atomic current-session provide projection (production SessionsService
+   * mirror): selection changes and provider-roster changes publish through
+   * this one source — the member the SlotsService host face hands the
+   * renderer's SessionProvider.
+   */
+  readonly currentProvideInfo: HostObservable<SessionMaybeProvideInfo>
+  private readonly records = new Map<SessionId, SessionRecord>()
+  /** The production provide channel (roster, materialization rules, current projection) — no test-side mirror. */
+  private readonly channel: SessionProvideChannel
+
+  /** Calls observed on the service-level face (open/clear), newest last. */
+  readonly calls: { method: 'open' | 'clear'; args: unknown[] }[] = []
+
+  /**
+   * @param stabilize - the owning runtime's act wrapper.
+   * @param rootCtx - the runtime's Cordis root; scope fibers mount under it.
+   */
+  constructor(private readonly stabilize: Stabilizer, private readonly rootCtx: Context) {
+    this.list = createSnapshotStore<SessionListState>({
+      ids: [], byId: {}, current: undefined, phase: 'ready',
+    })
+    this.channel = new SessionProvideChannel({
+      rebuildBundles: () => {
+        for (const record of this.records.values()) {
+          if (record.provideInfo !== undefined) {
+            record.provideInfo = this.channel.materializeInfo(this.bindingOf(record.session.sessionId, record))
+          }
+        }
+      },
+      resolveCurrent: () => this.maybeProvideInfo(this.list.getSnapshot().current),
+    })
+    this.currentProvideInfo = this.channel.currentProvideInfo
+    // The projection follows every current write, as in production.
+    this.list.subscribe(() => { this.channel.publishCurrent() })
+  }
+
+  /**
+   * Add a session from a fixture and (by default) make it current.
+   * @param fixture - identity + snapshot/summary overrides + behavior face.
+   * @param opts - pass `current: false` to add without selecting.
+   * @returns the stable session id (branded view of `fixture.id`).
+   */
+  async add(fixture: SessionFixture, opts?: { current?: boolean }): Promise<SessionId> {
+    const id = fixture.id as SessionId
+    if (this.records.has(id)) throw new Error(`test session "${id}" already added`)
+    const summary: SessionSummary = {
+      id,
+      displayTitle: fixture.id,
+      running: false,
+      blank: false,
+      updatedAt: this.records.size + 1,
+      ...fixture.summary,
+    }
+    const snapshot = createSnapshotStore<ConversationSnapshot>({
+      ...conversationSnapshot(id),
+      ...fixture.snapshot,
+    })
+    this.records.set(id, {
+      summary,
+      snapshot,
+      session: new FixtureSession(id, snapshot, fixture.session ?? {}),
+      scope: undefined,
+      scopeFiber: undefined,
+      provideInfo: undefined,
+    })
+    await this.stabilize(() => {
+      this.list.update((draft) => {
+        draft.ids.push(id)
+        draft.byId[id] = summary
+        if (opts?.current !== false) draft.current = id
+      })
+    })
+    return id
+  }
+
+  /**
+   * Update a session's conversation snapshot through an immer draft (the
+   * live-stream stand-in: components subscribed via useSession re-render).
+   * @param id - session id.
+   * @param mutate - draft mutator.
+   */
+  async updateSnapshot(id: string, mutate: (draft: ConversationSnapshot) => void): Promise<void> {
+    const record = this.require(id)
+    await this.stabilize(() => { record.snapshot.update(mutate) })
+  }
+
+  /**
+   * Switch the current selection (undefined = the no-session empty state).
+   * @param id - session id to select, or undefined to clear.
+   */
+  async setCurrent(id: string | undefined): Promise<void> {
+    if (id !== undefined) this.require(id)
+    await this.stabilize(() => {
+      this.list.update((draft) => { draft.current = id as SessionId | undefined })
+    })
+  }
+
+  /**
+   * Remove a session: list row, scope fiber, and per-session store instances
+   * (with persisted state) die together — the same single lifecycle axis the
+   * production SessionsService drives on session death, minus staging.
+   * @param id - session id.
+   */
+  async remove(id: string): Promise<void> {
+    const record = this.require(id)
+    this.records.delete(id as SessionId)
+    await this.stabilize(async () => {
+      this.list.update((draft) => {
+        draft.ids = draft.ids.filter(existing => existing !== id)
+        const { [id as SessionId]: _dead, ...rest } = draft.byId
+        draft.byId = rest
+        if (draft.current === id) draft.current = undefined
+      })
+      if (record.scopeFiber !== undefined) await record.scopeFiber.dispose()
+      this.rootCtx.get('slots')?.pruneStoreScope(id)
+    })
+  }
+
+  /**
+   * Register a per-session standard-props provider (production `provide`
+   * contract: hooks become `use<Name>` selector hooks on the render side,
+   * props spread verbatim; duplicate names fail loud at materialization).
+   * @param descriptor - static member roster plus per-session resolver.
+   * @returns disposer removing the provider.
+   */
+  provide(descriptor: SessionProvideDescriptor): () => void {
+    return this.channel.provide(descriptor)
+  }
+
+  /**
+   * Resolve the definite per-session standard-props bundle (host face member).
+   * @param id - session id.
+   * @returns the identity-stable bundle, or undefined for unknown sessions.
+   */
+  provideInfo(id: string): SessionProvideInfo | undefined {
+    const record = this.records.get(id as SessionId)
+    if (record === undefined) return undefined
+    record.provideInfo ??= this.channel.materializeInfo(this.bindingOf(id as SessionId, record))
+    return record.provideInfo
+  }
+
+  /**
+   * Resolve the current-session-optional standard kit (host face member):
+   * unknown or absent ids return the static no-session projection.
+   * @param id - current session id, when selected.
+   * @returns a definite or no-session provide bundle.
+   */
+  maybeProvideInfo(id: string | undefined): SessionMaybeProvideInfo {
+    return (id === undefined ? undefined : this.provideInfo(id)) ?? this.channel.maybeInfo
+  }
+
+  /**
+   * Resolve (mint on first touch) the session-scoped Cordis context through
+   * the production `createScope`, so real `scopeOf`/scope-addressed services
+   * resolve it.
+   * @param id - session id.
+   * @returns the scoped context, or undefined for unknown sessions.
+   */
+  scope(id: string): Context | undefined {
+    const record = this.records.get(id as SessionId)
+    if (record === undefined) return undefined
+    if (record.scope === undefined) {
+      const handle = createScope(this.rootCtx, id as SessionId)
+      record.scope = handle.ctx
+      record.scopeFiber = handle.fiber
+    }
+    return record.scope
+  }
+
+  /**
+   * Session assembly binding (inject factories and provide resolvers receive it).
+   * @param id - session id.
+   * @returns sessionId + behavior face + scoped ctx, or undefined when unknown.
+   */
+  binding(id: string): TestSessionBinding | undefined {
+    const record = this.records.get(id as SessionId)
+    if (record === undefined) return undefined
+    return this.bindingOf(id as SessionId, record)
+  }
+
+  /**
+   * Read the session scope tag off a context (service-method seam mirror).
+   * @param ctx - any client context.
+   * @returns the session id, or undefined on root contexts.
+   */
+  scopeOf(ctx: Context): SessionId | undefined {
+    return scopeOf(ctx)
+  }
+
+  /**
+   * Resolve the scoped session face off a context (production `sessionOf`
+   * mirror).
+   * @param ctx - any client context.
+   * @returns the fixture session face, or undefined off-scope.
+   */
+  sessionOf(ctx: Context): SessionFace | undefined {
+    const id = scopeOf(ctx)
+    if (id === undefined) return undefined
+    return this.records.get(id)?.session
+  }
+
+  /**
+   * Service-level selection call (recorded, then applied to the list store
+   * synchronously — inject callbacks call this outside any act window; the
+   * store notify is microtask-batched so the next stabilized step observes it).
+   * @param id - session id.
+   */
+  open(id: SessionId): void {
+    this.calls.push({ method: 'open', args: [id] })
+    this.require(id)
+    this.list.update((draft) => { draft.current = id })
+  }
+
+  /** Clear the current selection (recorded; the production no-session flow). */
+  clear(): void {
+    this.calls.push({ method: 'clear', args: [] })
+    this.list.update((draft) => { draft.current = undefined })
+  }
+
+  /**
+   * The session face of a fixture (typed view for assertions; fixture
+   * behavior methods are grafted onto it).
+   * @param id - session id.
+   * @returns the FixtureSession the binding and provide channel carry.
+   */
+  behavior(id: string): FixtureSession {
+    return this.require(id).session
+  }
+
+  /** Dispose minted scope fibers (runtime dispose path). */
+  async disposeScopes(): Promise<void> {
+    for (const record of this.records.values()) {
+      if (record.scopeFiber !== undefined) {
+        await record.scopeFiber.dispose()
+        record.scope = undefined
+        record.scopeFiber = undefined
+      }
+    }
+  }
+
+  private bindingOf(id: SessionId, record: SessionRecord): TestSessionBinding {
+    const ctx = this.scope(id)
+    /* v8 ignore next 2 -- bindingOf only runs for a live record, whose scope
+     * always resolves; kept so a future caller cannot mint a ctx-less binding. */
+    if (ctx === undefined) throw new Error(`test session "${id}" resolved no scope`)
+    return { sessionId: id, session: record.session, ctx }
+  }
+
+  private require(id: string): SessionRecord {
+    const record = this.records.get(id as SessionId)
+    if (record === undefined) throw new Error(`test session "${id}" is not added`)
+    return record
+  }
+}

packages/client/test-runtime/src/snapshot.ts

@@ -0,0 +1,89 @@
+/**
+ * DOM snapshot hygiene: a vitest snapshot serializer that keeps `.snap`
+ * files structural. Two normalizations, both on a clone (the live DOM is
+ * untouched, so class/tag queries keep working):
+ *
+ * - CSS-module scoped class names (`_frame_334d2d`, this repo's
+ *   `_[local]_[hash]` shape) fold back to their semantic local (`frame`), so
+ *   CSS edits do not churn snapshots.
+ * - `<svg>` internals collapse to a `data-content` fingerprint on the svg
+ *   element: path geometry is print noise, but the fingerprint still flips
+ *   when an icon's artwork actually changes.
+ */
+import { expect } from 'vitest'
+import type { SnapshotSerializer } from 'vitest'
+
+/** One scoped class token: `_<local>_<hash>` (local may itself contain underscores). */
+const SCOPED_CLASS = /^_(.+)_[a-z0-9]+$/
+
+/** Fold scoped tokens in one class attribute value; foreign tokens pass through. */
+function normalizeClassValue(value: string): string {
+  return value
+    .split(/\s+/)
+    .filter(token => token !== '')
+    .map(token => token.replace(SCOPED_CLASS, '$1'))
+    .join(' ')
+}
+
+/** FNV-1a 32-bit over the svg markup: deterministic, dependency-free fingerprint. */
+function fingerprint(markup: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < markup.length; i++) {
+    hash ^= markup.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0')
+}
+
+/** svg elements of a subtree, the root included when it is one. */
+function svgsOf(root: Element): Element[] {
+  const svgs: Element[] = [...root.querySelectorAll('svg')]
+  if (root.tagName.toLowerCase() === 'svg') svgs.unshift(root)
+  return svgs
+}
+
+/** Whether serializing this subtree needs a normalized clone. */
+function needsNormalization(root: Element): boolean {
+  const scoped = [root, ...root.querySelectorAll('[class]')].some((el) => {
+    const value = el.getAttribute('class')
+    return value !== null && value.split(/\s+/).some(token => SCOPED_CLASS.test(token))
+  })
+  return scoped || svgsOf(root).some(svg => svg.childNodes.length > 0)
+}
+
+/**
+ * The serializer plugin. Matches DOM elements whose subtree carries a scoped
+ * class or svg internals; serializes a normalized clone, which no longer
+ * matches, so printing falls through to the built-in DOM element serializer.
+ */
+export const domSnapshotSerializer: SnapshotSerializer = {
+  test(value: unknown): boolean {
+    return typeof Element !== 'undefined' && value instanceof Element && needsNormalization(value)
+  },
+  serialize(value, config, indentation, depth, refs, printer): string {
+    const clone = (value as Element).cloneNode(true) as Element
+    for (const el of [clone, ...clone.querySelectorAll('[class]')]) {
+      const raw = el.getAttribute('class')
+      if (raw !== null) el.setAttribute('class', normalizeClassValue(raw))
+    }
+    for (const svg of svgsOf(clone)) {
+      if (svg.childNodes.length === 0) continue
+      svg.setAttribute('data-content', fingerprint(svg.innerHTML))
+      svg.replaceChildren()
+    }
+    return printer(clone, config, indentation, depth, refs)
+  },
+}
+
+let registered = false
+
+/**
+ * Register {@link domSnapshotSerializer} with vitest's expect (idempotent).
+ * SlotTestRuntime.create() calls this; specs that snapshot DOM outside the
+ * runtime import and call it themselves.
+ */
+export function registerDomSnapshotSerializer(): void {
+  if (registered) return
+  registered = true
+  expect.addSnapshotSerializer(domSnapshotSerializer)
+}

packages/client/test-runtime/src/workspaces.ts

@@ -0,0 +1,147 @@
+/** Test-owned workspaces face: the renderer standard-kit observable plus recorded actions. */
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  IWorkspaces, SessionId, SnapshotStore, WorkspaceId, WorkspaceListState, WorkspaceView,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { workspaceListState } from './fixtures.ts'
+import type { Stabilizer } from './fixtures.ts'
+
+/**
+ * Workspaces test double. Implements the same IWorkspaces face features
+ * receive as `ctx.workspaces`, so a production face change breaks this
+ * double at compile time. Every action records into {@link
+ * TestWorkspaces.calls}; defaults are inert echoes — feature tests needing
+ * richer behavior replace them via {@link TestWorkspaces.stub}.
+ */
+export class TestWorkspaces implements IWorkspaces {
+  /** The useWorkspaces standard feed. */
+  readonly list: SnapshotStore<WorkspaceListState>
+
+  /** Calls observed on the action face, newest last. */
+  readonly calls: { method: string; args: unknown[] }[] = []
+
+  /** Replaceable action seat: feature tests may stub richer behavior. */
+  private readonly stubs = new Map<string, (...args: unknown[]) => unknown>()
+
+  /**
+   * @param stabilize - the owning runtime's act wrapper.
+   */
+  constructor(private readonly stabilize: Stabilizer) {
+    this.list = createSnapshotStore<WorkspaceListState>(workspaceListState())
+  }
+
+  /**
+   * Update the workspace list state through an immer draft.
+   * @param mutate - draft mutator.
+   */
+  async update(mutate: (draft: WorkspaceListState) => void): Promise<void> {
+    await this.stabilize(() => { this.list.update(mutate) })
+  }
+
+  /**
+   * Replace an action's behavior (the recorded call is still appended first).
+   * @param method - action name (e.g. 'connectWorkspace').
+   * @param impl - replacement behavior.
+   */
+  stub(method: string, impl: (...args: unknown[]) => unknown): void {
+    this.stubs.set(method, impl)
+  }
+
+  /**
+   * Connect a workspace to its reusable/new blank session (recorded). The
+   * default resolves the workspace id back as the session id; stub for
+   * cross-session flows.
+   * @param workspaceId - target workspace.
+   * @returns the connected session id.
+   */
+  async connectWorkspace(workspaceId: WorkspaceId): Promise<SessionId> {
+    this.calls.push({ method: 'connectWorkspace', args: [workspaceId] })
+    const stub = this.stubs.get('connectWorkspace')
+    if (stub !== undefined) return await (stub(workspaceId) as Promise<SessionId>)
+    return `session-of-${workspaceId}` as SessionId
+  }
+
+  /**
+   * New-session flow (recorded; stubbed behavior runs when installed).
+   * @param workspaceId - optional explicit workspace target.
+   */
+  startSession(workspaceId?: WorkspaceId): void {
+    this.calls.push({ method: 'startSession', args: [workspaceId] })
+    this.stubs.get('startSession')?.(workspaceId)
+  }
+
+  /**
+   * Create a Workspace (recorded). The default echoes a view derived from
+   * the input; stub for failure or list-coupled flows.
+   * @param input - exactly one Host create spelling.
+   * @returns the created Workspace view.
+   */
+  async create(input: { name: string } | { path: string }): Promise<WorkspaceView> {
+    this.calls.push({ method: 'create', args: [input] })
+    const stub = this.stubs.get('create')
+    if (stub !== undefined) return await (stub(input) as Promise<WorkspaceView>)
+    const title = 'name' in input ? input.name : input.path
+    return {
+      workspaceId: `ws-${title}` as WorkspaceId,
+      title,
+      path: 'path' in input ? input.path : `/${input.name}`,
+      sessionIds: [],
+    } as unknown as WorkspaceView
+  }
+
+  /**
+   * Open a path with the host OS default application (recorded; default no-op).
+   * @param path - host-resolvable path.
+   */
+  async openPath(path: string): Promise<void> {
+    this.calls.push({ method: 'openPath', args: [path] })
+    await (this.stubs.get('openPath')?.(path) as Promise<void> | undefined)
+  }
+
+  /**
+   * Directory picker (recorded). The default cancels (null); stub to select.
+   * @returns the picked path, or null.
+   */
+  async pickDirectory(): Promise<string | null> {
+    this.calls.push({ method: 'pickDirectory', args: [] })
+    const stub = this.stubs.get('pickDirectory')
+    if (stub !== undefined) return await (stub() as Promise<string | null>)
+    return null
+  }
+
+  /**
+   * Rename a Workspace (recorded). The default echoes a minimal view.
+   * @param workspaceId - target workspace.
+   * @param title - new title.
+   * @returns the updated view.
+   */
+  async rename(workspaceId: WorkspaceId, title: string): Promise<WorkspaceView> {
+    this.calls.push({ method: 'rename', args: [workspaceId, title] })
+    const stub = this.stubs.get('rename')
+    if (stub !== undefined) return await (stub(workspaceId, title) as Promise<WorkspaceView>)
+    return { workspaceId, title, path: `/${title}`, sessionIds: [] } as unknown as WorkspaceView
+  }
+
+  /**
+   * Delete a Workspace (recorded; default no-op).
+   * @param workspaceId - target workspace.
+   */
+  async delete(workspaceId: WorkspaceId): Promise<void> {
+    this.calls.push({ method: 'delete', args: [workspaceId] })
+    await (this.stubs.get('delete')?.(workspaceId) as Promise<void> | undefined)
+  }
+
+  /**
+   * Move an accounted session (recorded). The default echoes a minimal view.
+   * @param workspaceId - target workspace.
+   * @param sessionId - session to move.
+   * @param beforeSessionId - anchor; omitted appends.
+   * @returns the updated view.
+   */
+  async insertSessionBefore(workspaceId: WorkspaceId, sessionId: SessionId, beforeSessionId?: SessionId): Promise<WorkspaceView> {
+    this.calls.push({ method: 'insertSessionBefore', args: [workspaceId, sessionId, beforeSessionId] })
+    const stub = this.stubs.get('insertSessionBefore')
+    if (stub !== undefined) return await (stub(workspaceId, sessionId, beforeSessionId) as Promise<WorkspaceView>)
+    return { workspaceId, title: '', path: '', sessionIds: [sessionId] } as unknown as WorkspaceView
+  }
+}

packages/client/test-runtime/tests/__snapshots__/runtime.spec.tsx.snap

@@ -0,0 +1,37 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`single-slot mounting (declare + renderSlot) > folds class hashes and collapses svg internals in snapshots, leaving the live DOM alone 1`] = `
+<div
+  data-slot="trt.panel"
+>
+  <div
+    class="frame plain"
+  >
+    <span
+      class="label"
+    >
+      styled
+    </span>
+    <svg
+      aria-hidden="true"
+      data-content="2bfa09dc"
+      viewBox="0 0 16 16"
+    />
+  </div>
+</div>
+`;
+
+exports[`single-slot mounting edge arms > serializes childless svg untouched next to scoped classes 1`] = `
+<div
+  data-slot="trt.panel"
+>
+  <div
+    class="frame"
+  >
+    <svg
+      aria-hidden="true"
+      viewBox="0 0 1 1"
+    />
+  </div>
+</div>
+`;

packages/client/test-runtime/tests/invariant.spec.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as TestRuntimeInvariant from '@deepseek-ai/dsh-client-test-runtime/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+describe('invariant companion', () => {
+  it('registers under the package name with an empty installer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(InvariantService, { enabled: true })
+    await expect(ctx.plugin(TestRuntimeInvariant).await()).resolves.toBeDefined()
+  })
+})

packages/client/test-runtime/tests/runtime.spec.tsx

@@ -0,0 +1,546 @@
+// @vitest-environment jsdom
+/**
+ * SlotTestRuntime behavior: root declaration + rendering, session
+ * add/update/switch/remove through the real renderer, shared store identity
+ * and scope pruning, feature mount/dispose cascade, and runtime disposal
+ * idempotence. All through the production SlotsService + createSlotRenderer
+ * stack — this suite is the fixture the migrated feature specs rely on.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup } from '@testing-library/react'
+import { defineStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { PropsRenderSlots, SessionStandardProps } from '@deepseek-ai/dsh-client-ui-slots'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'trt.panel': { kind: 'single'; scope: 'root'; owner: { label?: string } }
+    'trt.chat': { kind: 'single'; scope: 'session' }
+    'trt.rows': { kind: 'list'; scope: 'root' }
+  }
+}
+
+afterEach(cleanup)
+
+type FrameProps = PropsRenderSlots<'trt.panel' | 'trt.chat' | 'trt.rows'>
+
+/** Root frame declaring all three suite slots (render sites for each kind). */
+function Frame({ renderSlot, SessionProvider }: FrameProps) {
+  return (
+    <>
+      {renderSlot('trt.panel', { label: 'from-owner' }, { fallback: <i>no panel</i> })}
+      <SessionProvider empty={() => <i>no session</i>}>
+        {() => renderSlot('trt.chat', {})}
+      </SessionProvider>
+      {renderSlot('trt.rows', {})}
+    </>
+  )
+}
+
+const CHILDREN = {
+  'trt.panel': { kind: 'single', scope: 'root' },
+  'trt.chat': { kind: 'single', scope: 'session' },
+  'trt.rows': { kind: 'list', scope: 'root' },
+} as const
+
+async function runtimeWithFrame() {
+  const runtime = await SlotTestRuntime.create()
+  await runtime.root.declare(CHILDREN, Frame)
+  return runtime
+}
+
+describe('root declaration and rendering', () => {
+  it('renders declared slots through the real renderer: fallback, then a live registration, then unload', async () => {
+    const runtime = await runtimeWithFrame()
+    const view = runtime.renderRoot()
+    expect(view.container.textContent).toContain('no panel')
+
+    let dispose = (): void => {}
+    await runtime.flush() // no-op guard: flush outside mutations is safe
+    await (async () => {
+      dispose = runtime.slots.register(
+        { name: 'trt.panel' },
+        ({ label }: { label?: string }) => <b>panel:{label}</b>)
+      await runtime.flush()
+    })()
+    expect(view.container.textContent).toContain('panel:from-owner')
+    dispose()
+    await runtime.flush()
+    expect(view.container.textContent).toContain('no panel')
+    await runtime.dispose()
+  })
+
+  it('fails loud when rendering with no root declaration (production boot-order check)', async () => {
+    const runtime = await SlotTestRuntime.create()
+    expect(() => runtime.renderRoot()).toThrow(/'root' has no registration/)
+    await runtime.dispose()
+  })
+})
+
+describe('sessions', () => {
+  it('drives SessionProvider: empty state, current session, switch, live snapshot updates', async () => {
+    const runtime = await runtimeWithFrame()
+    runtime.slots.register({ name: 'trt.chat' }, (props: SessionStandardProps) => {
+      const running = props.useSession(s => s.running)
+      return <span>chat:{props.sessionId}:{String(running)}</span>
+    })
+    const view = runtime.renderRoot()
+    expect(view.container.textContent).toContain('no session')
+
+    await runtime.sessions.add({ id: 's1' })
+    expect(view.container.textContent).toContain('chat:s1:false')
+
+    await runtime.sessions.updateSnapshot('s1', (draft) => { draft.running = true })
+    expect(view.container.textContent).toContain('chat:s1:true')
+
+    await runtime.sessions.add({ id: 's2' }) // becomes current by default
+    expect(view.container.textContent).toContain('chat:s2:false')
+
+    await runtime.sessions.setCurrent(undefined)
+    expect(view.container.textContent).toContain('no session')
+    await runtime.sessions.setCurrent('s1')
+    expect(view.container.textContent).toContain('chat:s1:true')
+    await runtime.dispose()
+  })
+
+  it('add with current:false keeps the selection; unknown ids fail loud on the mutators', async () => {
+    const runtime = await runtimeWithFrame()
+    await runtime.sessions.add({ id: 's1' })
+    await runtime.sessions.add({ id: 's2' }, { current: false })
+    expect(runtime.sessions.list.getSnapshot().current).toBe('s1')
+    expect(runtime.sessions.list.getSnapshot().ids).toEqual(['s1', 's2'])
+    await expect(runtime.sessions.add({ id: 's1' })).rejects.toThrow(/already added/)
+    await expect(runtime.sessions.setCurrent('ghost')).rejects.toThrow(/not added/)
+    await expect(runtime.sessions.updateSnapshot('ghost', () => {})).rejects.toThrow(/not added/)
+    await expect(runtime.sessions.remove('ghost')).rejects.toThrow(/not added/)
+    expect(() => runtime.sessions.behavior('ghost')).toThrow(/not added/)
+    await runtime.dispose()
+  })
+
+  it('mints REAL-tag scopes lazily and resolves them through the production scopeOf; bindings expose the behavior face', async () => {
+    const runtime = await runtimeWithFrame()
+    const prompt = vi.fn()
+    await runtime.sessions.add({ id: 's1', session: { prompt } })
+
+    expect(runtime.sessions.provideInfo('ghost')).toBeUndefined()
+    expect(runtime.sessions.scope('ghost')).toBeUndefined()
+    expect(runtime.sessions.binding('ghost')).toBeUndefined()
+
+    const scope = runtime.sessions.scope('s1')!
+    expect(runtime.sessions.scope('s1')).toBe(scope) // stable per session
+    expect(runtime.sessions.scopeOf(scope)).toBe('s1')
+    expect(runtime.sessions.scopeOf(runtime.ctx)).toBeUndefined()
+    // sessionOf resolves the behavior face off the scope tag.
+    expect(runtime.sessions.sessionOf(scope)).toBe(runtime.sessions.behavior('s1'))
+    expect(runtime.sessions.sessionOf(runtime.ctx)).toBeUndefined()
+
+    const binding = runtime.sessions.binding('s1')!
+    expect(binding.sessionId).toBe('s1')
+    expect(binding.ctx).toBe(scope)
+    ;(binding.session as { prompt: () => void }).prompt()
+    expect(prompt).toHaveBeenCalledOnce()
+    expect(runtime.sessions.behavior('s1')).toBe(binding.session)
+    // The binding's session doubles as the conversation observable face.
+    expect((binding.session as { getSnapshot(): { sessionId: string } }).getSnapshot().sessionId).toBe('s1')
+
+    // A scoped service resolves through the scope ctx (scope-addressed pattern).
+    runtime.provide('probe', { hello: 'world' })
+    expect(scope.get('probe')).toEqual({ hello: 'world' })
+    await runtime.dispose()
+  })
+
+  it('materializes provide bundles: built-in session hook, custom providers, no-session projection', async () => {
+    const runtime = await runtimeWithFrame()
+    await runtime.sessions.add({ id: 's1' })
+
+    const info = runtime.sessions.provideInfo('s1')!
+    expect(info.sessionId).toBe('s1')
+    expect(info.hooks['session']).toBeDefined() // the built-in useSession source
+    expect(runtime.sessions.provideInfo('s1')).toBe(info) // identity-stable
+
+    // A feature provider (the ui-conversation input pattern): declared names
+    // materialize per session and land in the no-session roster as undefined.
+    const off = runtime.sessions.provide({
+      hooks: ['probe'],
+      props: ['probeActions'],
+      resolve: binding => ({
+        hooks: { probe: { getSnapshot: () => binding.sessionId, subscribe: () => () => {} } },
+        props: { probeActions: { poke: () => {} } },
+      }),
+    })
+    const enriched = runtime.sessions.provideInfo('s1')!
+    expect(enriched.hooks['probe']?.getSnapshot()).toBe('s1')
+    expect(enriched.props['probeActions']).toBeDefined()
+    const maybe = runtime.sessions.maybeProvideInfo(undefined)
+    expect(maybe.sessionId).toBeUndefined()
+    expect(Object.keys(maybe.hooks)).toEqual(['session', 'probe'])
+    expect(runtime.sessions.maybeProvideInfo('s1')).toBe(runtime.sessions.provideInfo('s1'))
+    expect(runtime.sessions.maybeProvideInfo('ghost').sessionId).toBeUndefined()
+
+    // Misdeclared providers fail loud AT REGISTRATION (the production
+    // channel rebuilds live bundles eagerly and rolls the roster back):
+    // missing hook, missing prop, duplicate hook, duplicate prop.
+    expect(() => runtime.sessions.provide({ hooks: ['void'], resolve: () => ({}) }))
+      .toThrow(/missing hook "void"/)
+    expect(() => runtime.sessions.provide({ props: ['void'], resolve: () => ({}) }))
+      .toThrow(/missing prop "void"/)
+    expect(() => runtime.sessions.provide({
+      hooks: ['session'],
+      resolve: () => ({ hooks: { session: { getSnapshot: () => 0, subscribe: () => () => {} } } }),
+    })).toThrow(/duplicate hook "session"/)
+    const propA = runtime.sessions.provide({ props: ['twice'], resolve: () => ({ props: { twice: 1 } }) })
+    expect(() => runtime.sessions.provide({ props: ['twice'], resolve: () => ({ props: { twice: 2 } }) }))
+      .toThrow(/duplicate prop "twice"/)
+    propA()
+    // The rejected registrations rolled back: the roster still materializes.
+    expect(runtime.sessions.provideInfo('s1')).toBeDefined()
+    off()
+    off() // disposer is idempotent
+    expect(Object.keys(runtime.sessions.maybeProvideInfo(undefined).hooks)).toEqual(['session'])
+    await runtime.dispose()
+  })
+
+  it('records service-face calls; open() moves the selection and clear() empties it', async () => {
+    const runtime = await runtimeWithFrame()
+    await runtime.sessions.add({ id: 's1' })
+    await runtime.sessions.add({ id: 's2' })
+    runtime.sessions.open('s1' as SessionId)
+    await runtime.flush()
+    expect(runtime.sessions.list.getSnapshot().current).toBe('s1')
+    runtime.sessions.clear()
+    await runtime.flush()
+    expect(runtime.sessions.list.getSnapshot().current).toBeUndefined()
+    expect(runtime.sessions.calls).toEqual([
+      { method: 'open', args: ['s1'] },
+      { method: 'clear', args: [] },
+    ])
+    await runtime.dispose()
+  })
+})
+
+describe('stores', () => {
+  const createSuiteStore = () => defineStore({
+    init: () => ({ note: '' }),
+    persist: 'trt.store',
+    actions: { setNote: (d, note: string) => { d.note = note } },
+  })
+
+  it('resolves per-session instances via the host face: shared identity, isolation, action-driven re-render', async () => {
+    const runtime = await runtimeWithFrame()
+    const handle = createSuiteStore()
+    runtime.slots.register(
+      { name: 'trt.chat', store: handle },
+      (props: SessionStandardProps & { useStore: <S>(sel: (s: { note: string }) => S) => S }) =>
+        <span>note:{props.useStore(s => s.note)}</span>)
+    const view = runtime.renderRoot()
+    await runtime.sessions.add({ id: 's1' })
+
+    expect(() => runtime.storeOf('trt.panel')).toThrow(/no registration/)
+    const store = runtime.storeOf('trt.chat', 's1')
+    await runtime.flush()
+    ;(store.actions['setNote'] as (note: string) => void)('hello')
+    await runtime.flush()
+    expect(view.container.textContent).toContain('note:hello')
+    expect(runtime.storeOf('trt.chat', 's1')).toBe(store) // cached per scope key
+
+    await runtime.sessions.add({ id: 's2' })
+    const other = runtime.storeOf('trt.chat', 's2')
+    expect(other).not.toBe(store)
+    expect(other.getSnapshot()).toEqual({ note: '' })
+    await runtime.dispose()
+  })
+
+  it('storeOf guards: before renderRoot, and for storeless entries', async () => {
+    const runtime = await runtimeWithFrame()
+    runtime.slots.register({ name: 'trt.panel' }, () => null)
+    expect(() => runtime.storeOf('trt.panel')).toThrow(/before renderRoot/)
+    runtime.renderRoot()
+    expect(() => runtime.storeOf('trt.panel')).toThrow(/declares no store/)
+    await runtime.dispose()
+  })
+
+  it('remove() prunes the session store scope: persisted state clears, a re-added session starts fresh', async () => {
+    const runtime = await runtimeWithFrame()
+    const handle = createSuiteStore()
+    runtime.slots.register({ name: 'trt.chat', store: handle }, () => null)
+    runtime.renderRoot()
+    await runtime.sessions.add({ id: 's1' })
+
+    const doomed = runtime.storeOf('trt.chat', 's1')
+    ;(doomed.actions['setNote'] as (note: string) => void)('buried')
+    expect(localStorage.getItem('trt.store.s1')).not.toBeNull()
+
+    await runtime.sessions.remove('s1')
+    expect(localStorage.getItem('trt.store.s1')).toBeNull()
+    expect(runtime.sessions.list.getSnapshot().ids).toEqual([])
+    expect(runtime.sessions.provideInfo('s1')).toBeUndefined()
+
+    await runtime.sessions.add({ id: 's1' })
+    const reborn = runtime.storeOf('trt.chat', 's1')
+    expect(reborn).not.toBe(doomed)
+    expect(reborn.getSnapshot()).toEqual({ note: '' })
+    await runtime.dispose()
+  })
+
+  it('remove() also disposes a minted scope fiber; removing a non-current session keeps the selection', async () => {
+    const runtime = await runtimeWithFrame()
+    await runtime.sessions.add({ id: 's1' })
+    await runtime.sessions.add({ id: 's2' }, { current: false })
+    const scope = runtime.sessions.scope('s1')!
+    await runtime.sessions.remove('s2')
+    expect(runtime.sessions.list.getSnapshot().current).toBe('s1')
+    await runtime.sessions.remove('s1')
+    expect(scope.fiber.uid).toBeNull() // disposed fiber loses its uid
+    expect(runtime.sessions.list.getSnapshot().current).toBeUndefined()
+    await runtime.dispose()
+  })
+})
+
+describe('workspaces', () => {
+  it('feeds useWorkspaces and records/stubs intent actions', async () => {
+    const runtime = await runtimeWithFrame()
+    runtime.slots.register(
+      { name: 'trt.panel' },
+      (props: { useWorkspaces: <S>(sel: (s: { phase: string }) => S) => S }) =>
+        <span>ws:{props.useWorkspaces(s => s.phase)}</span>)
+    const view = runtime.renderRoot()
+    expect(view.container.textContent).toContain('ws:ready')
+
+    await runtime.workspaces.update((draft) => { draft.phase = 'pending' })
+    expect(view.container.textContent).toContain('ws:pending')
+
+    runtime.workspaces.startSession('w1' as WorkspaceId)
+    await expect(runtime.workspaces.connectWorkspace('w2' as WorkspaceId)).resolves.toBe('session-of-w2')
+    expect(runtime.workspaces.calls).toEqual([
+      { method: 'startSession', args: ['w1'] },
+      { method: 'connectWorkspace', args: ['w2'] },
+    ])
+    const stub = vi.fn(() => Promise.resolve('other' as never))
+    runtime.workspaces.stub('connectWorkspace', stub)
+    await expect(runtime.workspaces.connectWorkspace('w3' as WorkspaceId)).resolves.toBe('other')
+    expect(stub).toHaveBeenCalledOnce()
+    await runtime.dispose()
+  })
+})
+
+describe('feature mount and disposal', () => {
+  it('mounts a plugin on a real fiber; dispose() cascades entries, declared children, and services', async () => {
+    const runtime = await runtimeWithFrame()
+    runtime.provide('layout', { openDetails: vi.fn() })
+    const feature = await runtime.mount({
+      inject: ['slots', 'layout'],
+      apply: (ctx: typeof runtime.ctx) => {
+        ctx.provide('feature-service', { ok: true })
+        ctx.slots.register({
+          name: 'trt.rows',
+          id: 'row-1',
+          children: { 'trt.rows.hole': { kind: 'single', scope: 'root' } },
+        } as never, ((props: { renderSlot: (key: string, owner: object) => unknown }) =>
+          <div data-testid="row">{props.renderSlot('trt.rows.hole', {}) as React.ReactNode}</div>) as never)
+      },
+    })
+    const view = runtime.renderRoot()
+    expect(view.getByTestId('row')).toBeTruthy()
+    expect(runtime.ctx.get('feature-service')).toEqual({ ok: true })
+    expect(runtime.slots.entries('trt.rows')).toHaveLength(1)
+
+    await feature.dispose()
+    await feature.dispose() // idempotent
+    expect(runtime.slots.entries('trt.rows')).toHaveLength(0)
+    expect(runtime.slots.spec('trt.rows.hole' as never)).toBeUndefined()
+    expect(runtime.ctx.get('feature-service')).toBeUndefined()
+    expect(view.queryByTestId('row')).toBeNull()
+    await runtime.dispose()
+  })
+
+  it('mount fails loud on missing services instead of suspending forever', async () => {
+    const runtime = await runtimeWithFrame()
+    await expect(runtime.mount({ inject: ['slots', 'absent-service'], apply: () => {} }))
+      .rejects.toThrow(/missing service\(s\) absent-service/)
+    await runtime.dispose()
+  })
+
+  it('runtime dispose is idempotent, unmounts views, disposes mounted features, and clears persisted state', async () => {
+    const runtime = await runtimeWithFrame()
+    const feature = await runtime.mount({
+      inject: ['slots'],
+      apply: (ctx: typeof runtime.ctx) => { ctx.slots.register({ name: 'trt.panel' }, () => <b>p</b>) },
+    })
+    const view = runtime.renderRoot()
+    expect(view.container.textContent).toContain('p')
+    localStorage.setItem('trt.leftover', 'x')
+
+    await runtime.dispose()
+    expect(view.container.innerHTML).toBe('')
+    expect(feature.fiber.uid).toBeNull()
+    expect(localStorage.getItem('trt.leftover')).toBeNull()
+    await runtime.dispose() // idempotent
+    await expect(runtime.dispose()).resolves.toBeUndefined()
+  })
+})
+
+describe('single-slot mounting (declare + renderSlot)', () => {
+  it('renders one slot inside its data-slot wrapper and updates owner props in place', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({ 'trt.panel': { kind: 'single', scope: 'root' } })
+    runtime.slots.register(
+      { name: 'trt.panel' },
+      ({ label }: { label?: string }) => <b data-testid="panel">{label ?? 'none'}</b>)
+    const slot = runtime.renderSlot('trt.panel', { label: 'first' })
+    expect(slot.container.getAttribute('data-slot')).toBe('trt.panel')
+    expect(slot.view.getByTestId('panel').textContent).toBe('first')
+
+    const panel = slot.view.getByTestId('panel')
+    slot.update({ label: 'second' })
+    expect(slot.view.getByTestId('panel').textContent).toBe('second')
+    // In-place re-render: the element identity survived the owner flip.
+    expect(slot.view.getByTestId('panel')).toBe(panel)
+    await runtime.dispose()
+  })
+
+  it('views sibling slots of one tree separately and rejects undeclared keys', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({
+      'trt.panel': { kind: 'single', scope: 'root' },
+      'trt.rows': { kind: 'list', scope: 'root' },
+    })
+    runtime.slots.register({ name: 'trt.panel' }, () => <b>panel</b>)
+    runtime.slots.register({ name: 'trt.rows', id: 'r1' }, () => <i>row</i>)
+    const panel = runtime.renderSlot('trt.panel', {})
+    const rows = runtime.renderSlot('trt.rows', {})
+    expect(panel.container.textContent).toBe('panel')
+    expect(rows.container.textContent).toBe('row')
+    expect(() => runtime.renderSlot('trt.chat', {})).toThrow(/without declare\(\)/)
+    await runtime.dispose()
+  })
+
+  it('folds class hashes and collapses svg internals in snapshots, leaving the live DOM alone', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({ 'trt.panel': { kind: 'single', scope: 'root' } })
+    runtime.slots.register({ name: 'trt.panel' }, () => (
+      <div className="_frame_a1b2c3 plain">
+        <span className="_label_ff00aa">styled</span>
+        <svg viewBox="0 0 16 16" aria-hidden="true">
+          <path d="M0 0L16 16" fill="currentColor" />
+        </svg>
+      </div>
+    ))
+    const slot = runtime.renderSlot('trt.panel', {})
+    expect(slot.container).toMatchSnapshot()
+    // The serializer works on a clone: the live DOM keeps hashes and paths.
+    expect(slot.container.querySelector('div')!.className).toBe('_frame_a1b2c3 plain')
+    expect(slot.container.querySelector('svg path')).not.toBeNull()
+    await runtime.dispose()
+  })
+})
+
+describe('fixture session face', () => {
+  it('fail-loud stubs name the missing verb; supplied overrides run instead', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.sessions.add({ id: 's1' })
+    const bare = runtime.sessions.behavior('s1')
+    expect(() => bare.prompt()).toThrow(/prompt is not stubbed/)
+    expect(() => bare.cancel()).toThrow(/cancel is not stubbed/)
+    expect(() => bare.loadOlder()).toThrow(/loadOlder is not stubbed/)
+    await runtime.dispose()
+  })
+
+  it('projections faces are identity-stable per key, read absent, and notify on set', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.sessions.add({ id: 's1' })
+    const session = runtime.sessions.behavior('s1')
+    const face = session.projections.faceOf('todos')
+    expect(session.projections.faceOf('todos')).toBe(face)
+    expect(face.getSnapshot()).toBeUndefined()
+    const seen: unknown[] = []
+    const off = face.subscribe(() => { seen.push(face.getSnapshot()) })
+    session.projections.set('todos', [1, 2])
+    expect(seen).toEqual([[1, 2]])
+    off()
+    session.projections.set('todos', [3])
+    expect(seen).toEqual([[1, 2]]) // unsubscribed
+    // A never-subscribed key sets without listeners (the empty-notify arm).
+    session.projections.set('untouched', 1)
+    // The provide bundle hands the same store to the render side.
+    const info = runtime.sessions.provideInfo('s1')!
+    expect(info.projections?.faceOf('todos').getSnapshot()).toEqual([3])
+    // A roster change rebuilds the ALREADY-materialized bundle eagerly
+    // (production channel semantics: mounted entries must see the provider)
+    // and skips never-materialized records (they pick the roster up lazily).
+    await runtime.sessions.add({ id: 's-lazy' }, { current: false })
+    const offProbe = runtime.sessions.provide({
+      hooks: ['probe2'],
+      resolve: () => ({ hooks: { probe2: { getSnapshot: () => 1, subscribe: () => () => {} } } }),
+    })
+    const rebuilt = runtime.sessions.provideInfo('s1')!
+    expect(rebuilt).not.toBe(info)
+    expect(rebuilt.hooks['probe2']).toBeDefined()
+    offProbe()
+    await runtime.dispose()
+  })
+})
+
+describe('workspaces action face', () => {
+  it('records every IWorkspaces verb with inert defaults and honors stubs', async () => {
+    const runtime = await SlotTestRuntime.create()
+    const ws = runtime.workspaces
+    const created = await ws.create({ name: 'alpha' })
+    expect(created.title).toBe('alpha')
+    const registered = await ws.create({ path: '/tmp/beta' })
+    expect(registered.path).toBe('/tmp/beta')
+    await expect(ws.pickDirectory()).resolves.toBeNull()
+    const renamed = await ws.rename('w1' as WorkspaceId, 'Renamed')
+    expect(renamed.title).toBe('Renamed')
+    await ws.delete('w1' as WorkspaceId)
+    await ws.openPath('/proj/file.ts')
+    const moved = await ws.insertSessionBefore('w1' as WorkspaceId, 's1' as SessionId, 's2' as SessionId)
+    expect(moved.sessionIds).toEqual(['s1'])
+    expect(ws.calls.map(c => c.method)).toEqual(
+      ['create', 'create', 'pickDirectory', 'rename', 'delete', 'openPath', 'insertSessionBefore'])
+
+    ws.stub('create', () => Promise.resolve({ workspaceId: 'ws-x', title: 'X', path: '/x', sessionIds: [] } as never))
+    ws.stub('pickDirectory', () => Promise.resolve('/picked'))
+    ws.stub('rename', () => Promise.resolve({ workspaceId: 'w1', title: 'S', path: '/s', sessionIds: [] } as never))
+    ws.stub('delete', () => Promise.resolve())
+    ws.stub('openPath', () => Promise.resolve())
+    ws.stub('insertSessionBefore', () => Promise.resolve({ workspaceId: 'w1', title: '', path: '', sessionIds: [] } as never))
+    expect((await ws.create({ name: 'y' })).title).toBe('X')
+    await expect(ws.pickDirectory()).resolves.toBe('/picked')
+    expect((await ws.rename('w1' as WorkspaceId, 'z')).title).toBe('S')
+    await ws.delete('w1' as WorkspaceId)
+    await ws.openPath('/other')
+    expect((await ws.insertSessionBefore('w1' as WorkspaceId, 's1' as SessionId)).sessionIds).toEqual([])
+    await runtime.dispose()
+  })
+})
+
+describe('single-slot mounting edge arms', () => {
+  it('renderSlot fails loud after dispose and after an external unmount', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({ 'trt.panel': { kind: 'single', scope: 'root' } })
+    runtime.slots.register({ name: 'trt.panel' }, () => <b>p</b>)
+    runtime.renderSlot('trt.panel', {})
+    // RTL cleanup empties the mounted tree behind the runtime's back: the
+    // wrapper lookup names the state instead of returning a dead container.
+    cleanup()
+    expect(() => runtime.renderSlot('trt.panel', {})).toThrow(/rendered no wrapper/)
+    await runtime.dispose()
+    // After dispose the root registration is gone: the production boot-order
+    // check fires before any wrapper lookup.
+    expect(() => runtime.renderSlot('trt.panel', {})).toThrow(/'root' has no registration/)
+  })
+
+  it('serializes childless svg untouched next to scoped classes', async () => {
+    const runtime = await SlotTestRuntime.create()
+    await runtime.declare({ 'trt.panel': { kind: 'single', scope: 'root' } })
+    runtime.slots.register({ name: 'trt.panel' }, () => (
+      <div className="_frame_a1b2c3">
+        <svg viewBox="0 0 1 1" aria-hidden="true" />
+      </div>
+    ))
+    const slot = runtime.renderSlot('trt.panel', {})
+    expect(slot.container).toMatchSnapshot()
+    await runtime.dispose()
+  })
+})

packages/client/test-runtime/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.client.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../ui-slots"
+    },
+    {
+      "path": "../web-react"
+    },
+    {
+      "path": "../runtime"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/ui-command/src/client/service.ts

@@ -9,10 +9,10 @@
 import { Service } from 'cordis'
 import type { Context } from 'cordis'
 import type { ConnectionHandle, SessionId } from '@deepseek-ai/dsh-client-connection/client'
-import type { ClientContext, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ClientContext, ISessions } from '@deepseek-ai/dsh-client-runtime/client'
 import type {
   CandidateRequest, ClientSessionContext, CommandClaim, PickOutcome, SlashCandidate, SlashPick,
-  SlashServiceContract, SubmitOutcome,
+  SubmitOutcome,
 } from '@deepseek-ai/dsh-client-ui-slash/client'
 import type { CommandContribution, CommandServiceContract } from './contract.ts'
 import type { CommandDescriptor } from './directory.ts'
@@ -46,7 +46,7 @@ export class CommandService extends Service implements CommandServiceContract {
       if (!result.ok) throw new Error(`command.list failed: ${result.error.code}: ${result.error.message}`)
       return result.value.commands
     })
-    const slash = ctx.get('slash') as SlashServiceContract | undefined
+    const slash = ctx.get('slash')
     if (slash === undefined) throw new Error('ui-command: slash service unavailable')
     ctx.effect(() => slash.registerSource({
       trigger: '/',
@@ -292,7 +292,7 @@ export class CommandService extends Service implements CommandServiceContract {
     return this.sessions().scope(id)
   }
 
-  private sessions(): SessionsService {
+  private sessions(): ISessions {
     const sessions = this.ctx.get('sessions')
     if (sessions === undefined) throw new Error('ui-command: sessions service unavailable')
     return sessions

packages/client/ui-conversation/src/client/apply.ts

@@ -1,7 +1,7 @@
 /** Registers the conversation components, shared store, and service callbacks. */
 import type { Context } from 'cordis'
 import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ISessions, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { ViewTab } from './contract/views.ts'
 import type {
@@ -10,6 +10,7 @@ import type {
 import { resolveToolPath } from './contract/tool-call-model.ts'
 import { createChatStore } from './stores.ts'
 import { ConversationService } from './service.ts'
+import type { IConversation } from './service.ts'
 import { InputHub } from './input/hub.ts'
 import { InputBar } from './skeleton/InputBar.tsx'
 import { ChatView } from './chat/ChatView.tsx'
@@ -24,8 +25,8 @@ import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 /** Services required by the conversation plugin. */
 export const inject = ['slots', 'layout', 'sessions', 'workspaces']
 
-/** Resolve the session-scoped conversation service (scope-addressed send/cancel), failing loud. */
-function scopedConversation(sessions: SessionsService, id: SessionId): ConversationService {
+/** Resolve the session-scoped conversation face (scope-addressed send/cancel), failing loud. */
+function scopedConversation(sessions: ISessions, id: SessionId): IConversation {
   const scoped = sessions.scope(id)
   if (scoped === undefined) throw new Error(`ui-conversation: session "${id}" resolved no scope`)
   const conversation = scoped.get('conversation')

packages/client/ui-conversation/src/client/index.ts

@@ -3,10 +3,9 @@
  * between the independently implemented skeleton and chat domains; `apply.ts`
  * owns their slot assembly.
  */
-import type { ConversationService } from './service.ts'
-
 export { apply, inject } from './apply.ts'
 export { ConversationService } from './service.ts'
+export type { IConversation } from './service.ts'
 
 export type {
   CallId, ChatStoreState, SelectionTarget, ViewTab,
@@ -22,6 +21,7 @@ export type {
 
 declare module 'cordis' {
   interface Context {
-    conversation: ConversationService
+    /** The outward face only; the concrete service stays inside this plugin. */
+    conversation: import('./service.ts').IConversation
   }
 }

packages/client/ui-conversation/src/client/input/hub.ts

@@ -8,9 +8,8 @@
  * bail events) and owns the default-sink choreography: every session is a
  * real host entity, so the sink is one unconditional prompt path.
  */
-import type { ClientContext, Session, SessionBinding, SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SlashController, SlashServiceContract } from '@deepseek-ai/dsh-client-ui-slash/client'
-import type {} from '@deepseek-ai/dsh-client-ui-slash/client'
+import type { ClientContext, ISessions, SessionBinding, SessionFace, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SlashController } from '@deepseek-ai/dsh-client-ui-slash/client'
 import { queueReadFaceOf } from '../queue/store.ts'
 import type { ComposerKeyboard, InputService, SessionInput } from './contract.ts'
 import type { PopupDismissFace } from './facade.ts'
@@ -113,7 +112,7 @@ export class InputHub implements InputService {
    * exactly one path; a failed first prompt is an ordinary prompt failure
    * (error strip via promptError, draft restored only while untouched).
    */
-  private sink(session: Session, text: string, mode: 'queue' | 'steer'): void {
+  private sink(session: SessionFace, text: string, mode: 'queue' | 'steer'): void {
     if (text === '') return
     const shell = this.shells.get(session.sessionId)
     // Commit, not an editable clear: undo must not resurrect sent content.
@@ -129,7 +128,7 @@ export class InputHub implements InputService {
   }
 
   private controller(actx: ClientContext): SlashController | undefined {
-    const slash = this.rootCtx.get('slash') as SlashServiceContract | undefined
+    const slash = this.rootCtx.get('slash')
     return slash?.sessionOf(actx)
   }
 
@@ -138,7 +137,7 @@ export class InputHub implements InputService {
     return command?.popupFor(actx)
   }
 
-  private sessions(): SessionsService {
+  private sessions(): ISessions {
     const sessions = this.rootCtx.get('sessions')
     if (sessions === undefined) throw new Error('conversation.input: sessions service unavailable')
     return sessions

packages/client/ui-conversation/src/client/queue/store.ts

@@ -5,7 +5,7 @@
  * reference-stable across unrelated snapshot swaps, so this is a pure
  * projection — no second store, no copy.
  */
-import type { ObservableSnapshot, Session } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ObservableSnapshot, SessionFace } from '@deepseek-ai/dsh-client-runtime/client'
 import type { QueuedMessage } from '../input/contract.ts'
 
 /**
@@ -13,10 +13,10 @@ import type { QueuedMessage } from '../input/contract.ts'
  * The wiring layer (T5) overlays this onto InputState.queue; the runtime
  * QueuedMessage and the input-contract QueuedMessage are structurally the
  * same frozen shape ({key, preview}).
- * @param session - the resident session instance.
+ * @param session - the resident session face.
  * @returns the queue read face (snapshot reference stable while the queue is unchanged).
  */
-export function queueReadFaceOf(session: Session): ObservableSnapshot<readonly QueuedMessage[]> {
+export function queueReadFaceOf(session: SessionFace): ObservableSnapshot<readonly QueuedMessage[]> {
   return {
     getSnapshot: () => session.getSnapshot().queue,
     subscribe: fn => session.subscribe(fn),

packages/client/ui-conversation/src/client/service.ts

@@ -12,24 +12,50 @@ import type { Context } from 'cordis'
 // Type-only imports: a plugin-to-plugin value import is a bundle purity
 // error, so scope resolution goes through the sessions service (scopeOf
 // method) instead of the standalone helper.
-import type { Session, SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
-import { InputHub } from './input/hub.ts'
+import type { ISessions, SessionFace, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { InputService } from './input/contract.ts'
+
+/**
+ * The outward conversation face (`ctx.conversation`): the scope-addressed
+ * verbs and the input registry other plugins may reach — and exactly what a
+ * test fake must supply.
+ */
+export interface IConversation {
+  /** The per-session input machine registry (InputService face). */
+  readonly input: InputService
+  /**
+   * Send a prompt into the caller scope's session.
+   * @param text - prompt text, sent verbatim as one text block.
+   * @param mode - queue after the current turn, or steer into it.
+   * @returns completion; business failures reject (and land in promptError).
+   */
+  send(text: string, mode: 'queue' | 'steer'): Promise<void>
+  /**
+   * Cancel the scoped session's in-flight turn.
+   * @returns completion; failures reject as in send.
+   */
+  cancel(): Promise<void>
+  /**
+   * Pull one older history page for the scoped session.
+   * @returns completion of the page pull.
+   */
+  loadOlder(): Promise<void>
+}
 
 /** Scope-addressed conversation service (root singleton, provided as `conversation`). */
-export class ConversationService extends Service {
+export class ConversationService extends Service implements IConversation {
   /** The per-session input machine registry (InputService face, design §5.2). */
-  readonly input: InputHub
+  readonly input: InputService
 
   /**
    * @param ctx - owning root context (the plugin apply context; the service
    * registers itself and follows that fiber's lifetime).
-   * @param config - the shared InputHub constructed by the plugin apply
-   * (shared with the slot inject factories); absent = own instance
-   * (object-layer tests that never touch slots).
+   * @param config - carries the InputService instance constructed by the
+   * plugin apply (the same InputHub the slot inject factories close over).
    */
-  constructor(ctx: Context, config?: { input?: InputHub }) {
+  constructor(ctx: Context, config: { input: InputService }) {
     super(ctx, 'conversation')
-    this.input = config?.input ?? new InputHub(ctx)
+    this.input = config.input
   }
 
   /**
@@ -57,8 +83,8 @@ export class ConversationService extends Service {
     await this.scopedSession('loadOlder').loadOlder()
   }
 
-  /** Resolve the caller scope's Session or throw on root contexts. */
-  private scopedSession(op: string): Session {
+  /** Resolve the caller scope's session face or throw on root contexts. */
+  private scopedSession(op: string): SessionFace {
     const id = this.scopeId(op)
     const binding = this.requireSessions().binding(id)
     if (binding === undefined) throw new Error(`conversation.${op}: session "${id}" resolved no binding`)
@@ -74,10 +100,9 @@ export class ConversationService extends Service {
     return id
   }
 
-  private requireSessions(): SessionsService {
-    // ctx.get instead of ctx.sessions: the typed Context merge is suspended
-    // while the client/host `sessions` declaration collision awaits
-    // arbitration (see the runtime package's Context merge note).
+  private requireSessions(): ISessions {
+    // Strict ctx.get, not the injection proxy: the scope-addressed pattern
+    // reads the service off whatever context the tracker rebound.
     const sessions = this.ctx.get('sessions')
     if (sessions === undefined) throw new Error('conversation: sessions service unavailable')
     return sessions

packages/client/ui-conversation/tests/apply-inject.spec.tsx

@@ -1,144 +1,73 @@
 // @vitest-environment jsdom
 // apply inject factories exercised end to end against the terminal thin
-// shape: the conversation surface (views triple, send choreography incl.
-// optimistic clear + failure restore THROUGH the declared store actions,
-// openDetails = select action + layout orchestration, sessions.open
-// navigation), and the closeDetails details surface. Complements
-// chat-apply.spec.tsx (registration)
-// and selection-survival.spec.ts (store axis). History opening is NOT an
-// inject concern anymore — the runtime sessions service opens on watch
-// (sessions-service.spec.ts owns that behavior).
+// shape: the strict session surface (views triple, draft mirror), the
+// provide-channel input face (machine-sink submit choreography incl.
+// optimistic clear + failure restore), the resident surface (selectWorkspace
+// draft carrying), the composer-bar stop face, openDetails = select action +
+// layout orchestration, and the closeDetails details surface. Complements
+// chat-apply.spec.tsx (registration) and selection-survival.spec.tsx (store
+// axis). History opening is NOT an inject concern — the runtime sessions
+// service opens on watch (sessions-service.spec.ts owns that behavior).
+//
+// The inject surfaces are read off the ledger entries deliberately (typed at
+// this spec's own contract): these cases pin factory choreography the UI
+// guards would mask. Rendering-path acceptance lives in
+// chat-toolview-slot.spec.tsx.
 
-import { Context } from 'cordis'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { cleanup } from '@testing-library/react'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { SlotsService, scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
-import type {
-  SessionId, SessionListState, WorkspaceListState,
-} from '@deepseek-ai/dsh-client-runtime/client'
-import type { SlotRendererHost } from '@deepseek-ai/dsh-client-web-react'
+import { describe, expect, it, vi } from 'vitest'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionBehaviorOverrides } from '@deepseek-ai/dsh-client-test-runtime'
+import type { ISession, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
   ChatViewInjected, ComposerBarInjected, ConversationInjected, ConversationSessionInjected, DetailsInjected,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { createChatStore } from '../src/client/stores.ts'
 
-afterEach(cleanup)
-
 const ROOT = 'root-1' as SessionId
 
 type ChatInstance = ReturnType<ReturnType<typeof createChatStore>['create']>
 type ChatActions = ChatInstance['actions']
 
-const SCOPE_TAG: symbol = (() => {
-  const recorded: (string | symbol)[] = []
-  const spy = new Proxy(new Context(), {
-    get(target, prop, receiver) {
-      recorded.push(prop)
-      // Reflect.get is typed any; the probe only records property names.
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-      return Reflect.get(target, prop, receiver)
-    },
-  })
-  void scopeOf(spy)
-  const symbol = recorded.find((p): p is symbol => typeof p === 'symbol')
-  if (symbol === undefined) throw new Error('scopeOf probe recorded no symbol read')
-  return symbol
-})()
+/** ISession verb mocks, typed against the production face (['prompt'] etc. keep vitest mock ergonomics). */
+function sessionFakeFor() {
+  return {
+    open: vi.fn(() => Promise.resolve()),
+    loadOlder: vi.fn<ISession['loadOlder']>(() => Promise.resolve()),
+    prompt: vi.fn<ISession['prompt']>(() => Promise.resolve({ ok: true, value: { accepted: true } })),
+    cancel: vi.fn<ISession['cancel']>(() => Promise.resolve({ ok: true, value: { accepted: true } })),
+  } satisfies SessionBehaviorOverrides
+}
 
 async function bench() {
-  const ctx = new Context()
-  const slotsFiber = ctx.plugin(SlotsService)
-  await slotsFiber.await()
-  const slots = ctx.get('slots') as SlotsService
-
-  const listStore = createSnapshotStore<SessionListState>({
-    ids: [ROOT],
-    byId: { [ROOT]: { id: ROOT, title: 'R', displayTitle: 'R', cwd: '/proj', running: false, blank: false, updatedAt: 1 } },
-    current: ROOT,
-    phase: 'ready',
+  const runtime = await SlotTestRuntime.create()
+  const sessionFake = sessionFakeFor()
+  await runtime.sessions.add({
+    id: ROOT,
+    summary: { title: 'R', displayTitle: 'R', cwd: '/proj' },
+    session: sessionFake,
   })
-  const sessionFake = {
-    sessionId: ROOT,
-    open: vi.fn(() => Promise.resolve()),
-    loadOlder: vi.fn(() => Promise.resolve()),
-    prompt: vi.fn<() => Promise<{ ok: boolean; value?: object; error?: { code: string; message: string } }>>(
-      () => Promise.resolve({ ok: true, value: { accepted: true } })),
-    cancel: vi.fn<() => Promise<{ ok: boolean; value?: object; error?: { code: string; message: string } }>>(
-      () => Promise.resolve({ ok: true, value: { accepted: true } })),
-    // Observable face (the input machine's queue read face rides it).
-    getSnapshot: () => ({ queue: [] }),
-    subscribe: () => () => {},
-  }
-  const scopes = new Map<SessionId, Context>()
-  const mint = (id: SessionId): Context => {
-    let scoped = scopes.get(id)
-    if (scoped === undefined) {
-      scoped = ctx.plugin(() => {}).ctx.extend({ [SCOPE_TAG]: id })
-      scopes.set(id, scoped)
-    }
-    return scoped
-  }
-  type TestProvider = {
-    resolve(binding: { sessionId: SessionId; session: typeof sessionFake; ctx: Context }): {
-      hooks?: Record<string, unknown>
-      props?: Record<string, unknown>
-    }
-  }
-  const providers: TestProvider[] = []
-  const absentInfo = { sessionId: undefined, hooks: {}, props: {} }
-  const sessionsFake = {
-    list: listStore,
-    binding: (id: SessionId) => ({ sessionId: id, session: sessionFake, ctx: mint(id) }),
-    scope: (id: SessionId) => mint(id),
-    provideInfo: () => undefined,
-    currentProvideInfo: { getSnapshot: () => absentInfo, subscribe: () => () => {} },
-    provide: (descriptor: TestProvider) => { providers.push(descriptor); return () => {} },
-    scopeOf,
-    sessionOf: (actx: Context) => (scopeOf(actx) === undefined ? undefined : sessionFake),
-    open: vi.fn(),
-  }
-  ctx.provide('sessions', sessionsFake)
-  const workspaceStore = createSnapshotStore<WorkspaceListState>({
-    items: [], state: 'idle', phase: 'ready', error: null,
-    baselinesReady: true, recentWorkspaceId: undefined,
-  })
-  const workspacesFake = {
-    list: workspaceStore,
-    connectWorkspace: vi.fn(async () => ROOT),
-    openPath: vi.fn(async () => {}),
-  }
-  ctx.provide('workspaces', workspacesFake)
   const layoutFake = { openDetails: vi.fn(), closeDetails: vi.fn() }
-  ctx.provide('layout', layoutFake)
-  ctx.provide('locale', { bind: () => (key: string) => key })
+  runtime.provide('layout', layoutFake)
 
-  // The AppFrame role: the three conversation-package slots must be declared
-  // by a live entry before apply can contribute into them (the stand-in
-  // consumes renderSlot to satisfy the declare-means-render check).
-  slots.register({
-    name: 'root',
-    children: {
-      'conversation': { kind: 'single', scope: 'session-maybe' },
-      'details': { kind: 'single', scope: 'session' },
-    },
+  // The AppFrame role: the conversation-package slots must be declared by a
+  // live entry before apply can contribute into them.
+  await runtime.root.declare({
+    'conversation': { kind: 'single', scope: 'session-maybe' },
+    'details': { kind: 'single', scope: 'session' },
   }, (_p: { renderSlot?: unknown }) => null)
 
-  const fiber = ctx.plugin({ inject: [...inject], apply })
-  await fiber.await()
+  const feature = await runtime.mount({ inject: [...inject], apply })
 
-  // Reach the render-side entry view (inject + store handle) the way the
-  // renderer does: through the host face.
-  let host: SlotRendererHost | undefined
-  slots.install({ renderRoot: (h) => { host = h; return null } })
-  slots.renderSlot('root', {})
-  const hostFace = host!
-  const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.composer.bar' | 'conversation.view' | 'details') => hostFace.entriesOf(key)[0]!
+  // The host face (store resolution) exists only inside the installed
+  // renderer, so materialize it the way the shell does.
+  runtime.renderRoot()
+  const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.composer.bar' | 'conversation.view' | 'details') =>
+    runtime.slots.entries(key)[0]!
   /** Resolve store instance + call the inject the way the outlet would. */
   const conversationSurface = (id: SessionId) => {
     const entry = entryOf('conversation.session')
-    const instance = hostFace.storeOf(entry, id) as ChatInstance
+    const instance = runtime.storeOf('conversation.session', id) as ChatInstance
     const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ConversationSessionInjected)(
       id, instance.actions)
     return { instance, injected }
@@ -154,27 +83,28 @@ async function bench() {
   /** Same resolution for the chat entry riding the view ring. */
   const chatViewSurface = (id: SessionId) => {
     const entry = entryOf('conversation.view')
-    const instance = hostFace.storeOf(entry, id) as ChatInstance
+    const instance = runtime.storeOf('conversation.view', id) as ChatInstance
     const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ChatViewInjected)(
       id, instance.actions)
     return { instance, injected }
   }
   /** Materialize the input provide contribution the way the runtime does. */
   const inputSurface = (id: SessionId) => {
-    const contribution = providers[0]!.resolve(sessionsFake.binding(id))
-    const state = contribution.hooks!['input'] as {
+    const info = runtime.sessions.provideInfo(id)!
+    const state = info.hooks['input'] as {
       getSnapshot: () => { draft: string }
       subscribe: (fn: () => void) => () => void
     }
-    const actions = contribution.props!['inputActions'] as {
+    const actions = info.props['inputActions'] as {
       setDraft: (text: string) => void
       submit: (mode?: 'queue' | 'steer') => void
     }
     return { state, actions }
   }
   return {
-    ctx, slots, hostFace, entryOf, conversationSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
-    sessionFake, sessionsFake, workspacesFake, layoutFake, mint,
+    runtime, feature, slots: runtime.slots, entryOf,
+    conversationSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
+    sessionFake, layoutFake,
   }
 }
 
@@ -190,6 +120,7 @@ describe('conversation slot inject surface', () => {
     const chatView = b.chatViewSurface(ROOT)
     chatView.injected.loadOlder()
     expect(b.sessionFake.loadOlder).toHaveBeenCalledTimes(1)
+    await b.runtime.dispose()
   })
 
   it('the provide-channel input face submits through the machine sink: trim, optimistic clear, failure restore without clobber', async () => {
@@ -208,14 +139,14 @@ describe('conversation slot inject surface', () => {
     await Promise.resolve()
     expect(b.sessionFake.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'hello' }], 'queue')
     // Failure: restored (draft still empty when the rejection lands).
-    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b' } })
+    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b', details: { reason: 'b' } } })
     actions.setDraft('retry me')
     actions.submit('queue')
     await vi.waitFor(() => {
       expect(state.getSnapshot().draft).toBe('retry me')
     })
     // Failure landing after new typing: no clobber (restore fills empty only).
-    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b' } })
+    b.sessionFake.prompt.mockResolvedValueOnce({ ok: false, error: { code: 'agent-busy', message: 'b', details: { reason: 'b' } } })
     actions.submit('queue')
     actions.setDraft('typed during flight')
     await new Promise(r => setTimeout(r, 0))
@@ -229,23 +160,25 @@ describe('conversation slot inject surface', () => {
     expect(mirrored).toEqual(['mirrored text'])
     unbind()
     // Stop failure is swallowed (promptError owns the surface).
-    b.sessionFake.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'x' } })
+    b.sessionFake.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'x', details: {} } })
     b.composerSurface(ROOT).stop()
     await new Promise(r => setTimeout(r, 0))
     expect(b.sessionFake.cancel).toHaveBeenCalledTimes(1)
+    await b.runtime.dispose()
   })
 
-  it('inject fails loud when the session resolves no scope or the scope lacks the service', async () => {
+  it('inject fails loud when the session resolves no binding or the scope lacks the service', async () => {
     const b = await bench()
     const entry = b.entryOf('conversation.composer.bar')
     const injectFn = entry.inject as unknown as (sessionId: SessionId) => ComposerBarInjected
-    // Unknown session: sessions.scope answers nothing.
-    ;(b.sessionsFake.scope as unknown) = () => undefined
-    expect(() => { injectFn(ROOT).stop() }).toThrow(/resolved no scope/)
-    // A scope minted outside the service tree: no conversation service on it.
-    const foreign = new Context()
-    ;(b.sessionsFake.scope as unknown) = () => foreign.plugin(() => {}).ctx.extend({})
-    expect(() => { injectFn(ROOT).stop() }).toThrow(/unavailable through the session scope/)
+    // Unknown session: the keyboard face's binding resolution answers nothing.
+    expect(() => { injectFn('ghost' as SessionId).stop() }).toThrow(/resolved no binding/)
+    // A scope whose service tree lost 'conversation' (the feature fiber
+    // unloaded while a retained inject closure re-runs): fails loud too.
+    const stop = injectFn(ROOT).stop
+    await b.feature.dispose()
+    expect(() => { stop() }).toThrow(/unavailable through the session scope/)
+    await b.runtime.dispose()
   })
 
   it('openDetails (chat view face) writes the selection through the store actions and opens the panel', async () => {
@@ -258,6 +191,7 @@ describe('conversation slot inject surface', () => {
     // writes land where the skeleton and details read.
     const conv = b.conversationSurface(ROOT)
     expect(conv.instance).toBe(instance)
+    await b.runtime.dispose()
   })
 
   it('openFile (chat view face) resolves against session cwd and calls workspaces.openPath', async () => {
@@ -265,8 +199,9 @@ describe('conversation slot inject surface', () => {
     const { injected } = b.chatViewSurface(ROOT)
     injected.openFile('src/a.ts')
     await vi.waitFor(() => {
-      expect(b.workspacesFake.openPath).toHaveBeenCalledWith('/proj/src/a.ts')
+      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['/proj/src/a.ts'] })
     })
+    await b.runtime.dispose()
   })
 
   it('routes navigation and workspace switching through the runtime owners, carrying the draft', async () => {
@@ -274,23 +209,73 @@ describe('conversation slot inject surface', () => {
     const { injected } = b.conversationSurface(ROOT)
     const resident = b.residentSurface(ROOT)
     injected.open(ROOT)
-    expect(b.sessionsFake.open).toHaveBeenCalledWith(ROOT)
+    expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [ROOT] })
     // Same-session connect (the picked workspace resolves to this session):
     // no draft movement, plain re-open.
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(ROOT))
     const { state, actions } = b.inputSurface(ROOT)
     actions.setDraft('carry me')
     void resident.selectWorkspace('workspace-1' as never)
-    await vi.waitFor(() => { expect(b.sessionsFake.open).toHaveBeenCalledTimes(2) })
-    expect(b.workspacesFake.connectWorkspace).toHaveBeenCalledWith('workspace-1')
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls.filter(c => c.method === 'open')).toHaveLength(2)
+    })
+    expect(b.runtime.workspaces.calls).toContainEqual({ method: 'connectWorkspace', args: ['workspace-1'] })
     expect(state.getSnapshot().draft).toBe('carry me')
     // Cross-session connect: the draft MOVES — the old machine empties, the
     // new session's machine receives the text, then navigation lands there.
     const OTHER = 'other-1' as SessionId
-    b.workspacesFake.connectWorkspace.mockResolvedValueOnce(OTHER)
+    await b.runtime.sessions.add({ id: OTHER }, { current: false })
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(OTHER))
     void resident.selectWorkspace('workspace-2' as never)
-    await vi.waitFor(() => { expect(b.sessionsFake.open).toHaveBeenCalledWith(OTHER) })
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [OTHER] })
+    })
     expect(state.getSnapshot().draft).toBe('')
     expect(b.inputSurface(OTHER).state.getSnapshot().draft).toBe('carry me')
+    await b.runtime.dispose()
+  })
+
+  it('selectWorkspace edge arms: no-session resident, empty-draft move, connect failure retryable', async () => {
+    const b = await bench()
+    // No-session resident (hero before any session): connect resolves and
+    // navigation proceeds without any draft choreography.
+    const noSession = b.residentSurface(undefined)
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(ROOT))
+    void noSession.selectWorkspace('workspace-0' as never)
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [ROOT] })
+    })
+
+    // Cross-session connect with an EMPTY draft: no move, no clearing.
+    const OTHER = 'b9-other' as SessionId
+    await b.runtime.sessions.add({ id: OTHER }, { current: false })
+    const resident = b.residentSurface(ROOT)
+    const { state } = b.inputSurface(ROOT)
+    expect(state.getSnapshot().draft).toBe('')
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.resolve(OTHER))
+    void resident.selectWorkspace('workspace-3' as never)
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [OTHER] })
+    })
+    expect(b.inputSurface(OTHER).state.getSnapshot().draft).toBe('')
+
+    // Connect failure: the rejection propagates to the caller (the view owns
+    // the rollback) and no further navigation happens.
+    const opens = b.runtime.sessions.calls.filter(c => c.method === 'open').length
+    b.runtime.workspaces.stub('connectWorkspace', () => Promise.reject(new Error('offline')))
+    await expect(resident.selectWorkspace('workspace-4' as never)).rejects.toThrow('offline')
+    expect(b.runtime.sessions.calls.filter(c => c.method === 'open')).toHaveLength(opens)
+    await b.runtime.dispose()
+  })
+
+  it('scopedConversation fails loud when the session resolves no scope', async () => {
+    const b = await bench()
+    // The chat-view inject resolves the scoped conversation service at inject
+    // time: an unlisted session hits the scope() === undefined throw directly.
+    const entry = b.entryOf('conversation.view')
+    const injectFn = entry.inject as unknown as (sessionId: SessionId, actions: unknown) => unknown
+    expect(() => injectFn('never-listed' as SessionId, {})).toThrow(/resolved no scope/)
+    await b.runtime.dispose()
   })
 
   it('views read face projects the ring ledger (subscribe/version through ctx.slots)', async () => {
@@ -313,6 +298,7 @@ describe('conversation slot inject surface', () => {
     off()
     off2()
     unsub()
+    await b.runtime.dispose()
   })
 })
 
@@ -325,9 +311,9 @@ describe('details inject surface', () => {
     injected.closeDetails()
     expect(b.layoutFake.closeDetails).toHaveBeenCalledTimes(1)
     // The shared handle: details resolves the SAME instance conversation writes.
-    const conv = b.hostFace.storeOf(b.entryOf('conversation.session'), ROOT)
-    const details = b.hostFace.storeOf(entry, ROOT)
+    const conv = b.runtime.storeOf('conversation.session', ROOT)
+    const details = b.runtime.storeOf('details', ROOT)
     expect(details).toBe(conv)
+    await b.runtime.dispose()
   })
-
 })

packages/client/ui-conversation/tests/chat-apply.spec.tsx

@@ -1,89 +1,53 @@
 // @vitest-environment jsdom
 // apply wiring: the conversation service provided, the chat view registered
 // as the first 'conversation.view' ring entry declaring the keyed toolview
-// hole, the three slot registrations land against a root entry's children
-// declarations (the AppFrame role), the shared store handle rides all session
-// entries, and the bash sample mounts through the load-order seam as a keyed
-// entry. Full-chain rendering belongs to the machinery spec
-// (chat-toolview-slot.spec.tsx) and the shell e2e; this spec stops at the
-// assembly surface.
+// hole, the slot registrations land against a root entry's children
+// declarations (the AppFrame role), the shared store handle rides all strict
+// session entries, and the bash sample + todo row mount through the
+// load-order seam as keyed entries. Full-chain rendering belongs to the
+// machinery spec (chat-toolview-slot.spec.tsx) and the shell e2e; this spec
+// stops at the assembly surface.
 
-import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
-import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SessionId, SessionListState } from '@deepseek-ai/dsh-client-runtime/client'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 const ROOT = 'root-1' as SessionId
 const CHILD = 'child-1' as SessionId
 
 async function bench() {
-  const ctx = new Context()
-  const slotsFiber = ctx.plugin(SlotsService)
-  await slotsFiber.await()
+  const runtime = await SlotTestRuntime.create()
+  await runtime.sessions.add({ id: ROOT, summary: { title: 'R', displayTitle: 'R' } }, { current: false })
+  await runtime.sessions.add(
+    { id: CHILD, summary: { title: 'C', displayTitle: 'C', parentId: ROOT } }, { current: false })
+  runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
 
-  const listStore = createSnapshotStore<SessionListState>({
-    ids: [ROOT, CHILD],
-    byId: {
-      [ROOT]: { id: ROOT, title: 'R', displayTitle: 'R', running: false, blank: false, updatedAt: 1 },
-      [CHILD]: { id: CHILD, title: 'C', displayTitle: 'C', parentId: ROOT, running: false, blank: false, updatedAt: 2 },
-    },
-    current: undefined,
-    phase: 'ready',
-  })
-  const absentInfo = { sessionId: undefined, hooks: {}, props: {} }
-  const sessionsFake = {
-    list: listStore,
-    binding: vi.fn(),
-    scope: () => undefined,
-    provideInfo: () => undefined,
-    currentProvideInfo: { getSnapshot: () => absentInfo, subscribe: () => () => {} },
-    provide: vi.fn(() => () => {}),
-    create: vi.fn(),
-    open: vi.fn(),
-    updateIntent: vi.fn(),
-  }
-  ctx.provide('sessions', sessionsFake)
-  ctx.provide('workspaces', {
-    startSession: vi.fn(),
-    sendSession: vi.fn(),
-    openPath: vi.fn(async () => {}),
-  })
-  ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
-  ctx.provide('locale', { bind: () => (key: string) => key })
-
-  // Declared by ui-layout's root entry in production; a stand-in root
-  // occupant declares them here so the contributions land (it consumes
-  // renderSlot to satisfy the declare-means-render check).
-  const slots = ctx.get('slots') as SlotsService
-  slots.register({
-    name: 'root',
-    children: {
-      'conversation': { kind: 'single', scope: 'session-maybe' },
-      'details': { kind: 'single', scope: 'session' },
-    },
+  // Declared by ui-layout's root entry in production; the test root declares
+  // them here so the contributions land.
+  await runtime.root.declare({
+    'conversation': { kind: 'single', scope: 'session-maybe' },
+    'details': { kind: 'single', scope: 'session' },
   }, (_p: { renderSlot?: unknown }) => null)
 
-  const fiber = ctx.plugin({ inject: [...inject], apply })
-  return { ctx, fiber, slots }
+  const feature = await runtime.mount({ inject: [...inject], apply })
+  return { runtime, feature, slots: runtime.slots }
 }
 
 /** First stored entry for a key (inject/store live directly on StoredEntry). */
-function renderEntryOf(slots: SlotsService, key: 'conversation' | 'conversation.session' | 'conversation.view' | 'details') {
+function renderEntryOf(slots: Awaited<ReturnType<typeof bench>>['slots'], key: 'conversation' | 'conversation.session' | 'conversation.view' | 'details') {
   return slots.entries(key)[0] as undefined | { inject?: unknown; store?: unknown }
 }
 
 describe('apply wiring', () => {
   it('provides the conversation service', async () => {
     const b = await bench()
-    await b.fiber.await()
-    expect(b.ctx.get('conversation')).toBeDefined()
+    expect(b.runtime.ctx.get('conversation')).toBeDefined()
+    await b.runtime.dispose()
   })
 
   it('registers the chat view as the first ring entry, declaring the keyed toolview hole', async () => {
     const b = await bench()
-    await b.fiber.await()
     const entries = b.slots.entries('conversation.view')
     expect(entries.map(e => e.options.id)).toEqual(['chat'])
     expect(entries[0]?.options.label).toBe('Chat')
@@ -91,11 +55,11 @@ describe('apply wiring', () => {
     // Declaring is claiming: the chat entry's registration put the hole on
     // the ledger with the contract's kind/scope.
     expect(b.slots.spec('conversation.chat.toolview')).toEqual({ kind: 'keyed', scope: 'session' })
+    await b.runtime.dispose()
   })
 
   it('occupies the slots + the ring; session entries share one store handle', async () => {
     const b = await bench()
-    await b.fiber.await()
     const conversation = renderEntryOf(b.slots, 'conversation')
     const conversationSession = renderEntryOf(b.slots, 'conversation.session')
     const chatView = renderEntryOf(b.slots, 'conversation.view')
@@ -111,21 +75,21 @@ describe('apply wiring', () => {
     // The hero workspace picker hole rides the conversation entry's children
     // declaration (the empty-state occupant is gone).
     expect(b.slots.spec('conversation.hero.workspace')).toEqual({ kind: 'single', scope: 'root' })
+    await b.runtime.dispose()
   })
 
   it('mounts the bash sample and the todo row as keyed entries through the load-order seam', async () => {
     const b = await bench()
-    await b.fiber.await()
     // Both registrant plugins' inject: ['slots', 'conversation'] resolved — the
     // service being present implies the chat entry declared the hole first.
     const entries = b.slots.entries('conversation.chat.toolview')
     expect(entries.map(e => e.options.key)).toEqual(['bash', 'todo_write'])
+    await b.runtime.dispose()
   })
 
   it('plugin fiber disposal collects every registration (unload cascade, ring and hole included)', async () => {
     const b = await bench()
-    await b.fiber.await()
-    await b.fiber.dispose()
+    await b.feature.dispose()
     expect(b.slots.entries('conversation')).toHaveLength(0)
     // The declared ring collapses with its declaring entry, and the chat
     // entry's keyed hole (with the sample's registration) collapses with it.
@@ -133,6 +97,7 @@ describe('apply wiring', () => {
     expect(b.slots.entries('conversation.chat.toolview')).toHaveLength(0)
     expect(b.slots.spec('conversation.chat.toolview')).toBeUndefined()
     expect(b.slots.entries('details')).toHaveLength(0)
-    expect(b.ctx.get('conversation')).toBeUndefined()
+    expect(b.runtime.ctx.get('conversation')).toBeUndefined()
+    await b.runtime.dispose()
   })
 })

packages/client/ui-conversation/tests/chat-toolview-slot.spec.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 // The dissolved tool ring's acceptance chain on the REAL machinery stack:
-// cordis Context + SlotsService ledger + the web-react renderer + this
-// package's own apply — no outlet twins. Proves the keyed
+// SlotTestRuntime (cordis Context + SlotsService ledger + the web-react
+// renderer) + this package's own apply — no outlet twins. Proves the keyed
 // 'conversation.chat.toolview' hole end to end: registered rows dispatch by
 // entryKey (the bash sample lands through its plugin), unregistered tools
 // fall back to GenericToolCard at the render site, live registration/unload
@@ -10,23 +10,16 @@
 // inject: ['slots', 'conversation'] load-order seam suspends on real fiber
 // semantics until the service (and with it the hole declaration) is present.
 
-import { Context } from 'cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { act, cleanup, fireEvent, render } from '@testing-library/react'
-import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type {
-  ConversationSnapshot, SessionId, SessionListState, ToolResultNode, WorkspaceListState,
-} from '@deepseek-ai/dsh-client-runtime/client'
-import { createSlotRenderer } from '@deepseek-ai/dsh-client-web-react'
+import { cleanup, fireEvent } from '@testing-library/react'
+import type { ISession, SessionId, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 const SID = 's1' as SessionId
 
-/** Identity-stable no-session bundle (uSES getSnapshot contract). */
-const ABSENT_INFO = { sessionId: undefined, hooks: {}, props: {} }
-
 afterEach(cleanup)
 // The chat store persists under its declared key; clear between cases.
 beforeEach(() => {
@@ -40,117 +33,38 @@ const toolResult = (seq: number, callId: string, name: string, args = '{"command
   content: [], isError: false, callView: null, resultView: null,
 })
 
-function snapshotWith(nodes: ToolResultNode[]): ConversationSnapshot {
-  return {
-    sessionId: SID, nodes, foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
-    pending: [], queue: [], running: false, composerPhase: 'active', removed: false, openState: 'open', openError: null,
-    hasMore: false, loadingOlder: false, promptError: null, blank: false, lastAgentError: null,
-  }
-}
-
 /** Test-owned AppFrame role: declares and renders the resident conversation area. */
 type AppRootProps = PropsRenderSlots<'conversation' | 'details'>
 function AppRoot({ renderSlot }: AppRootProps) {
   return <>{renderSlot('conversation', {})}</>
 }
 
+const LAYOUT_CHILDREN = {
+  'conversation': { kind: 'single', scope: 'session-maybe' },
+  'details': { kind: 'single', scope: 'session' },
+} as const
+
 /**
- * Real-stack bench: SlotsService plugin, renderer installed, sessions/layout
- * fakes at the service seams only (external boundaries), the package apply on
- * its own fiber, and the test AppFrame occupying 'root'.
+ * Real-stack bench: SlotTestRuntime with the session/layout doubles at the
+ * service seams only (external boundaries), the package apply on its own
+ * fiber, and the test AppFrame occupying 'root'.
  */
 async function bench(nodes: ToolResultNode[]) {
-  const ctx = new Context()
-  const slotsFiber = ctx.plugin(SlotsService)
-  await slotsFiber.await()
-  const slots = ctx.get('slots') as SlotsService
-
-  const session = createSnapshotStore<ConversationSnapshot>(snapshotWith(nodes))
-  const list = createSnapshotStore<SessionListState>({
-    ids: [SID],
-    byId: { [SID]: { id: SID, title: 'S', displayTitle: 'S', running: false, blank: false, updatedAt: 1 } },
-    current: SID,
-    phase: 'ready',
-  })
-  // Identity-stable provide bundle: the renderer caches hooks per source and
-  // inject results per bundle, both by object identity. Registered providers
-  // (the package's input contribution) materialize into it lazily, once.
-  const providers: ((binding: object) => { hooks?: object; props?: object })[] = []
-  let info: { sessionId: SessionId; hooks: object; props: object } | undefined
-  const scoped = { send: vi.fn(async () => {}), cancel: vi.fn(async () => {}) }
+  const runtime = await SlotTestRuntime.create()
   const layout = { openDetails: vi.fn(), closeDetails: vi.fn() }
-  const actxFake = { get: () => scoped, effect: () => {}, on: () => () => {} }
-  const bindingOf = (id: SessionId) => ({
-    sessionId: id,
-    ctx: actxFake,
+  runtime.provide('layout', layout)
+  await runtime.sessions.add({
+    id: SID,
+    summary: { title: 'S', displayTitle: 'S' },
+    snapshot: { nodes },
     session: {
-      sessionId: id,
-      loadOlder: vi.fn(),
-      prompt: vi.fn(async () => ({ ok: true, value: { accepted: true } })),
-      // Observable face for the input machine's queue read face.
-      getSnapshot: () => session.getSnapshot(),
-      subscribe: (fn: () => void) => session.subscribe(fn),
+      loadOlder: vi.fn<ISession['loadOlder']>(),
+      prompt: vi.fn<ISession['prompt']>(async () => ({ ok: true, value: { accepted: true } })),
     },
   })
-  const provideInfo = (id: string) => {
-    if (id !== SID) return undefined
-    if (info === undefined) {
-      const hooks: Record<string, unknown> = { session }
-      const props: Record<string, unknown> = {}
-      for (const provider of providers) {
-        const c = provider(bindingOf(SID))
-        Object.assign(hooks, c.hooks ?? {})
-        Object.assign(props, c.props ?? {})
-      }
-      info = { sessionId: SID, hooks, props }
-    }
-    return info
-  }
-  ctx.provide('sessions', {
-    list,
-    binding: bindingOf,
-    scope: () => actxFake,
-    provideInfo,
-    currentProvideInfo: {
-      getSnapshot: () => provideInfo(SID),
-      subscribe: () => () => {},
-    },
-    provide: (d: { resolve: (typeof providers)[number] }) => { providers.push(d.resolve); return () => {} },
-    scopeOf: () => SID,
-    create: vi.fn(),
-    open: vi.fn(),
-    updateIntent: vi.fn(),
-  })
-  const workspaces = {
-    list: createSnapshotStore<WorkspaceListState>({
-      items: [], state: 'idle', phase: 'ready', error: null,
-      baselinesReady: true, recentWorkspaceId: undefined,
-    }),
-    startSession: vi.fn(),
-    sendSession: vi.fn(),
-    openPath: vi.fn(async () => {}),
-  }
-  ctx.provide('workspaces', workspaces)
-  ctx.provide('layout', layout)
-  ctx.provide('locale', { bind: () => (key: string) => key })
-
-  slots.install(createSlotRenderer())
-  slots.register({
-    name: 'root',
-    children: {
-      'conversation': { kind: 'single', scope: 'session-maybe' },
-      'details': { kind: 'single', scope: 'session' },
-    },
-  }, AppRoot)
-
-  const fiber = ctx.plugin({ inject: [...inject], apply })
-  await fiber.await()
-  return { ctx, slots, fiber, session, list, layout, workspaces }
-}
-
-/** Render the whole tree through the ctx-level root seam (the shell's own entry). */
-function mountApp(slots: SlotsService) {
-  return render(<>{slots.renderSlot('root', {})}</>)
+  await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
+  const feature = await runtime.mount({ inject: [...inject], apply })
+  return { runtime, slots: runtime.slots, feature, layout }
 }
 
 describe('keyed toolview hole through the real machinery', () => {
@@ -159,7 +73,7 @@ describe('keyed toolview hole through the real machinery', () => {
       toolResult(3, 'c1', 'bash'),
       toolResult(4, 'c2', 'mystery', '{"n":1}'),
     ])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     // bash: the sample plugin's keyed registration took the row (root
     // session → global arm, decided inside the component off useSessions).
     expect(view.container.querySelector('[data-sample="bash-global"]')).not.toBeNull()
@@ -167,6 +81,7 @@ describe('keyed toolview hole through the real machinery', () => {
     expect(view.getByText('Build')).toBeTruthy()
     // mystery: no registration under that key → render-site fallback.
     expect(view.getByText('Tool call')).toBeTruthy()
+    await b.runtime.dispose()
   })
 
   it('renders top-level Cordis calls with lifecycle titles over the generic variants', async () => {
@@ -176,7 +91,7 @@ describe('keyed toolview hole through the real machinery', () => {
       toolResult(4, 'cordis-2', 'cordis_mount', JSON.stringify({ code })),
       toolResult(5, 'cordis-3', 'cordis_unmount', '{"id":"dyn-2"}'),
     ])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
 
     expect(view.container.querySelector('[data-tool="cordis_inspect"]')?.textContent).toContain('Inspect')
     const mounted = view.container.querySelector('[data-variant="code"]')
@@ -186,42 +101,46 @@ describe('keyed toolview hole through the real machinery', () => {
 
     fireEvent.click(mounted!.querySelector('button[aria-expanded]')!)
     expect(mounted!.querySelector('pre.shiki')?.textContent).toBe(code)
+    await b.runtime.dispose()
   })
 
   it('file-path clicks travel owner openFile → chat inject → workspaces.openPath', async () => {
     const b = await bench([toolResult(3, 'c1', 'read', '{"path":"src/a.ts"}')])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     view.getByText('src/a.ts').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
     await vi.waitFor(() => {
-      expect(b.workspaces.openPath).toHaveBeenCalledWith('src/a.ts')
+      expect(b.runtime.workspaces.calls).toContainEqual({ method: 'openPath', args: ['src/a.ts'] })
     })
+    await b.runtime.dispose()
   })
 
   it('bash summary clicks do not open details or host paths', async () => {
     const b = await bench([toolResult(3, 'c1', 'bash')])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     view.getByText('Build').click()
     expect(b.layout.openDetails).not.toHaveBeenCalled()
-    expect(b.workspaces.openPath).not.toHaveBeenCalled()
+    expect(b.runtime.workspaces.calls.some(c => c.method === 'openPath')).toBe(false)
+    await b.runtime.dispose()
   })
 
   it('a live keyed registration takes over its tool row and unload reverts to the fallback', async () => {
     const b = await bench([toolResult(3, 'c2', 'mystery', '{"n":1}')])
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     expect(view.getByText('Tool call')).toBeTruthy()
     let dispose = (): void => {}
-    await act(async () => {
-      dispose = b.slots.register(
-        { name: 'conversation.chat.toolview', key: 'mystery' },
-        () => <div data-testid="mystery-row" />)
-    })
+    dispose = b.slots.register(
+      { name: 'conversation.chat.toolview', key: 'mystery' },
+      () => <div data-testid="mystery-row" />)
+    await b.runtime.flush()
     // Per-key version tick: the row flipped without a remount of the view.
     expect(view.getByTestId('mystery-row')).toBeTruthy()
     expect(view.queryByText('Tool call')).toBeNull()
-    await act(async () => { dispose() })
+    dispose()
+    await b.runtime.flush()
     expect(view.queryByTestId('mystery-row')).toBeNull()
     expect(view.getByText('Tool call')).toBeTruthy()
+    await b.runtime.dispose()
   })
 
   it('a duplicate key registration fails loud at load', async () => {
@@ -230,6 +149,7 @@ describe('keyed toolview hole through the real machinery', () => {
       { name: 'conversation.chat.toolview', key: 'bash' },
       () => null,
     )).toThrow(/key "bash"/)
+    await b.runtime.dispose()
   })
 
   it('the inject channel feeds (sessionId) => I into the row component', async () => {
@@ -247,66 +167,33 @@ describe('keyed toolview hole through the real machinery', () => {
     }, ({ mark, poke }: ToolRowProps & { mark: string; poke: () => void }) => (
       <button data-testid="probe-row" onClick={poke}>{mark}</button>
     ))
-    const view = mountApp(b.slots)
+    const view = b.runtime.renderRoot()
     const row = view.getByTestId('probe-row')
     expect(row.textContent).toBe(`for:${SID}`)
     row.click()
     expect(poked).toEqual([SID])
+    await b.runtime.dispose()
   })
 })
 
 describe('registrant load-order seam', () => {
   it("suspends a registrant on inject: ['slots', 'conversation'] until the service (and the hole) exists", async () => {
-    const ctx = new Context()
-    const slotsFiber = ctx.plugin(SlotsService)
-    await slotsFiber.await()
-    const slots = ctx.get('slots') as SlotsService
-    ctx.provide('sessions', {
-      list: createSnapshotStore<SessionListState>({
-        ids: [], byId: {}, current: undefined, phase: 'ready',
-      }),
-      binding: () => undefined,
-      scope: () => undefined,
-      provideInfo: () => undefined,
-      currentProvideInfo: {
-        getSnapshot: () => ABSENT_INFO,
-        subscribe: () => () => {},
-      },
-      provide: () => () => {},
-      create: vi.fn(),
-      open: vi.fn(),
-      updateIntent: vi.fn(),
-    })
-    ctx.provide('workspaces', {
-      list: createSnapshotStore<WorkspaceListState>({
-        items: [], state: 'idle', phase: 'ready', error: null,
-        baselinesReady: true, recentWorkspaceId: undefined,
-      }),
-      startSession: vi.fn(),
-      sendSession: vi.fn(),
-      openPath: vi.fn(async () => {}),
-    })
-    ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
-    ctx.provide('locale', { bind: () => (key: string) => key })
-    slots.register({
-      name: 'root',
-      children: {
-        'conversation': { kind: 'single', scope: 'session-maybe' },
-        'details': { kind: 'single', scope: 'session' },
-      },
-    }, AppRoot)
+    const runtime = await SlotTestRuntime.create()
+    runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+    await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
 
     // Third-party posture, mounted BEFORE ui-conversation: real fiber inject
     // semantics hold it — apply must not run while 'conversation' is absent.
-    // (Plain arrow, not vi.fn: mock functions carry a prototype and trip the
-    // fiber's isConstructor branch.)
+    // Uses ctx.plugin directly (the deliberate-suspension escape hatch; mount()
+    // would fail loud on the missing service). (Plain arrow, not vi.fn: mock
+    // functions carry a prototype and trip the fiber's isConstructor branch.)
     let applyRuns = 0
-    const registrantApply = (registrantCtx: Context): void => {
+    const registrantApply = (registrantCtx: typeof runtime.ctx): void => {
       applyRuns += 1
       registrantCtx.slots.register(
         { name: 'conversation.chat.toolview', key: 'late' }, () => null)
     }
-    const late = ctx.plugin({
+    const late = runtime.ctx.plugin({
       name: 'late-registrant',
       inject: ['slots', 'conversation'],
       apply: registrantApply,
@@ -317,11 +204,11 @@ describe('registrant load-order seam', () => {
     // Mounting the package resolves the seam: service present ⟹ the chat
     // entry (and its hole declaration) is already on the ledger, so the
     // suspended registrant lands without an undeclared-slot throw.
-    const fiber = ctx.plugin({ inject: [...inject], apply })
-    await fiber.await()
+    await runtime.mount({ inject: [...inject], apply })
     await late.await()
     expect(applyRuns).toBe(1)
-    expect(slots.entries('conversation.chat.toolview').map(e => e.options.key))
+    expect(runtime.slots.entries('conversation.chat.toolview').map(e => e.options.key))
       .toEqual(expect.arrayContaining(['bash', 'late']))
+    await runtime.dispose()
   })
 })

packages/client/ui-conversation/tests/selection-survival.spec.ts

@@ -1,149 +0,0 @@
-// @vitest-environment jsdom
-/**
- * Exercises selection persistence through the real SlotsService store axis;
- * component stubs cannot prove per-session identity or disposal.
- */
-import { Context } from 'cordis'
-import { beforeEach, describe, expect, it } from 'vitest'
-import { createSnapshotStore, SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SessionId, SessionListState, WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
-import { createChatStore } from '../src/client/stores.ts'
-
-const sid = (s: string): SessionId => s as SessionId
-
-/** Identity-stable no-session bundle (uSES getSnapshot contract). */
-const ABSENT_INFO = { sessionId: undefined, hooks: {}, props: {} }
-
-interface Bench {
-  slots: SlotsService
-  chat: ReturnType<typeof createChatStore>
-}
-
-function bench(): Bench {
-  const ctx = new Context()
-  ctx.provide('sessions', {
-    list: createSnapshotStore<SessionListState>({
-      ids: [], byId: {}, current: undefined, phase: 'ready',
-    }),
-    provideInfo: () => undefined,
-    currentProvideInfo: {
-      getSnapshot: () => ABSENT_INFO,
-      subscribe: () => () => {},
-    },
-    provide: () => () => {},
-  })
-  ctx.provide('workspaces', {
-    list: createSnapshotStore<WorkspaceListState>({
-      items: [], state: 'idle', phase: 'ready', error: null,
-      baselinesReady: true, recentWorkspaceId: undefined,
-    }),
-  })
-  // Service self-registers as ctx 'slots' (cordis Service constructor).
-  const slots = new SlotsService(ctx)
-  const chat = createChatStore()
-  // The apply.ts shape: one shared handle across both session-slot
-  // registrations. 'conversation'/'details' must first exist in the ledger —
-  // register a root occupant declaring them (the AppFrame role; the stand-in
-  // consumes renderSlot to satisfy the declare-means-render check).
-  slots.register({
-    name: 'root',
-    children: {
-      'conversation': { kind: 'single', scope: 'session-maybe' },
-      'conversation.session': { kind: 'single', scope: 'session' },
-      'details': { kind: 'single', scope: 'session' },
-    },
-  }, (_p: { renderSlot?: unknown }) => null)
-  // apply.ts mounts the shared chat handle only under session-scope slots
-  // (the session-maybe 'conversation' shell carries no store).
-  slots.register({ name: 'conversation.session', store: chat }, () => null)
-  slots.register({ name: 'details', store: chat }, () => null)
-  return { slots, chat }
-}
-
-/** Resolve the store instance the renderer would hand a slot's component for a session. */
-function storeFor(b: Bench, slot: 'conversation.session' | 'details', sessionId: SessionId) {
-  const host = renderHost(b)
-  const entry = host.entriesOf(slot)[0]!
-  return host.storeOf(entry, sessionId)! as ReturnType<ReturnType<typeof createChatStore>['create']>
-}
-
-/** The host face is only built at renderSlot time; install a stub renderer once to reach it. */
-function renderHost(b: Bench): import('@deepseek-ai/dsh-client-ui-slots').SlotRendererHost {
-  const captured = (b as unknown as { _host?: import('@deepseek-ai/dsh-client-ui-slots').SlotRendererHost })
-  if (captured._host === undefined) {
-    b.slots.install({
-      renderRoot: (host) => {
-        captured._host = host
-        return null
-      },
-    })
-    b.slots.renderSlot('root', {})
-  }
-  return captured._host!
-}
-
-beforeEach(() => {
-  localStorage.clear()
-})
-
-describe('selection survives on the store seat', () => {
-  it('one session, two slots: conversation writes, details reads the SAME instance', () => {
-    const b = bench()
-
-    const conv = storeFor(b, 'conversation.session', sid('s1'))
-    const details = storeFor(b, 'details', sid('s1'))
-    conv.actions.select({ turnSeq: 3, callId: 'c1' })
-    expect(details.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
-    // Identity, not just value: the shared handle resolves one instance per scope key.
-    expect(details).toBe(conv)
-  })
-
-  it('sessions are isolated: s2 selection never bleeds into s1', () => {
-    const b = bench()
-
-    const one = storeFor(b, 'conversation.session', sid('s1'))
-    const two = storeFor(b, 'conversation.session', sid('s2'))
-    expect(two).not.toBe(one)
-    one.actions.select({ turnSeq: 1, callId: 'a' })
-    two.actions.select({ turnSeq: 9, callId: 'z' })
-    expect(one.store.getSnapshot().selection).toEqual({ turnSeq: 1, callId: 'a' })
-    expect(two.store.getSnapshot().selection).toEqual({ turnSeq: 9, callId: 'z' })
-  })
-
-  it('a list-projection update keeps instance identity and the selection value', () => {
-    const b = bench()
-    const id = sid('s1')
-    const projection = createSnapshotStore({ displayTitle: 's1' })
-
-    const store = storeFor(b, 'conversation.session', id)
-    store.actions.select({ turnSeq: 3, callId: 'c1' })
-    store.actions.setDraft('half-typed')
-
-    projection.set({ displayTitle: 'proj-a' })
-    expect(projection.getSnapshot().displayTitle).toBe('proj-a')
-
-    const after = storeFor(b, 'conversation.session', id)
-    expect(after).toBe(store)
-    expect(after.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
-    expect(after.store.getSnapshot().draft).toBe('half-typed')
-  })
-
-  it('session death buries the instance and its persisted draft', () => {
-    const b = bench()
-
-    const doomed = storeFor(b, 'conversation.session', sid('s1'))
-    doomed.actions.setDraft('to be buried')
-    doomed.actions.select({ turnSeq: 1 })
-    expect(localStorage.getItem('dsh.conversation.chat.s1')).not.toBeNull()
-
-    // SessionsService calls this public slot lifecycle seam when the scope dies.
-    b.slots.pruneStoreScope(sid('s1'))
-
-    // Persisted residue is gone with the session...
-    expect(localStorage.getItem('dsh.conversation.chat.s1')).toBeNull()
-    // ...and a re-created same-id session starts from a FRESH instance.
-    const reborn = storeFor(b, 'conversation.session', sid('s1'))
-    expect(reborn).not.toBe(doomed)
-    expect(reborn.store.getSnapshot()).toEqual({ selection: null, draft: '', view: null })
-  })
-})

packages/client/ui-conversation/tests/selection-survival.spec.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment jsdom
+/**
+ * Exercises selection persistence through the real SlotsService store axis;
+ * component stubs cannot prove per-session identity or disposal.
+ */
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { createChatStore } from '../src/client/stores.ts'
+
+const sid = (s: string): SessionId => s as SessionId
+
+type ChatInstance = ReturnType<ReturnType<typeof createChatStore>['create']>
+
+async function bench() {
+  const runtime = await SlotTestRuntime.create()
+  const chat = createChatStore()
+  // The apply.ts shape: one shared handle across both strict-session slot
+  // registrations ('conversation.session'/'details'); the session-maybe
+  // 'conversation' shell carries no store by design. The slots must first
+  // exist in the ledger — the test root declares them (the AppFrame role).
+  await runtime.root.declare({
+    'conversation': { kind: 'single', scope: 'session-maybe' },
+    'conversation.session': { kind: 'single', scope: 'session' },
+    'details': { kind: 'single', scope: 'session' },
+  }, (_p: { renderSlot?: unknown }) => null)
+  runtime.slots.register({ name: 'conversation.session', store: chat }, () => null)
+  runtime.slots.register({ name: 'details', store: chat }, () => null)
+  runtime.renderRoot() // materializes the host face storeOf resolves through
+  return { runtime, chat }
+}
+
+/** Resolve the store instance the renderer would hand a slot's component for a session. */
+function storeFor(b: Awaited<ReturnType<typeof bench>>, slot: 'conversation.session' | 'details', sessionId: SessionId) {
+  return b.runtime.storeOf(slot, sessionId) as ChatInstance
+}
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
+describe('selection survives on the store seat', () => {
+  it('one session, two slots: conversation writes, details reads the SAME instance', async () => {
+    const b = await bench()
+
+    const conv = storeFor(b, 'conversation.session', sid('s1'))
+    const details = storeFor(b, 'details', sid('s1'))
+    conv.actions.select({ turnSeq: 3, callId: 'c1' })
+    expect(details.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
+    // Identity, not just value: the shared handle resolves one instance per scope key.
+    expect(details).toBe(conv)
+    await b.runtime.dispose()
+  })
+
+  it('sessions are isolated: s2 selection never bleeds into s1', async () => {
+    const b = await bench()
+
+    const one = storeFor(b, 'conversation.session', sid('s1'))
+    const two = storeFor(b, 'conversation.session', sid('s2'))
+    expect(two).not.toBe(one)
+    one.actions.select({ turnSeq: 1, callId: 'a' })
+    two.actions.select({ turnSeq: 9, callId: 'z' })
+    expect(one.store.getSnapshot().selection).toEqual({ turnSeq: 1, callId: 'a' })
+    expect(two.store.getSnapshot().selection).toEqual({ turnSeq: 9, callId: 'z' })
+    await b.runtime.dispose()
+  })
+
+  it('a list-projection update keeps instance identity and the selection value', async () => {
+    const b = await bench()
+    const id = sid('s1')
+
+    const store = storeFor(b, 'conversation.session', id)
+    store.actions.select({ turnSeq: 3, callId: 'c1' })
+    store.actions.setDraft('half-typed')
+
+    // A projection churn elsewhere (list rows re-projected) must not touch
+    // store identity: drive the runtime's own list observable.
+    await b.runtime.sessions.add({ id, summary: { displayTitle: 'proj-a' } })
+    expect(b.runtime.sessions.list.getSnapshot().byId[id]?.displayTitle).toBe('proj-a')
+
+    const after = storeFor(b, 'conversation.session', id)
+    expect(after).toBe(store)
+    expect(after.store.getSnapshot().selection).toEqual({ turnSeq: 3, callId: 'c1' })
+    expect(after.store.getSnapshot().draft).toBe('half-typed')
+    await b.runtime.dispose()
+  })
+
+  it('session death buries the instance and its persisted draft', async () => {
+    const b = await bench()
+    await b.runtime.sessions.add({ id: 's1' })
+
+    const doomed = storeFor(b, 'conversation.session', sid('s1'))
+    doomed.actions.setDraft('to be buried')
+    doomed.actions.select({ turnSeq: 1 })
+    expect(localStorage.getItem('dsh.conversation.chat.s1')).not.toBeNull()
+
+    // TestSessions.remove drives the same public slot lifecycle seam the
+    // production SessionsService calls when the scope dies (pruneStoreScope).
+    await b.runtime.sessions.remove('s1')
+
+    // Persisted residue is gone with the session...
+    expect(localStorage.getItem('dsh.conversation.chat.s1')).toBeNull()
+    // ...and a re-created same-id session starts from a FRESH instance.
+    const reborn = storeFor(b, 'conversation.session', sid('s1'))
+    expect(reborn).not.toBe(doomed)
+    expect(reborn.store.getSnapshot()).toEqual({ selection: null, draft: '', view: null })
+    await b.runtime.dispose()
+  })
+})

packages/client/ui-conversation/tests/service-orchestration.spec.ts

@@ -1,39 +1,32 @@
 // @vitest-environment jsdom
+// ConversationService scope addressing over the runtime's real scope tag:
+// TestSessions mints tagged scopes through the production createScope, so the
+// service's scopeOf/binding path runs against production resolution (no local
+// tag probe).
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
-import { scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
 import { ConversationService } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { InputHub } from '../src/client/input/hub.ts'
 
-const sid = (id: string) => id as SessionId
-const SCOPE_TAG: symbol = (() => {
-  const reads: (string | symbol)[] = []
-  const proxy = new Proxy(new Context(), {
-    get(target, property, receiver): unknown {
-      reads.push(property)
-      return Reflect.get(target, property, receiver)
-    },
-  })
-  void scopeOf(proxy)
-  return reads.find((value): value is symbol => typeof value === 'symbol')!
-})()
-
-async function bench(withSessions = true) {
-  const ctx = new Context()
+async function bench() {
+  const runtime = await SlotTestRuntime.create()
   const prompt = vi.fn(() => Promise.resolve({ ok: true as const, value: { accepted: true as const } }))
   const cancel = vi.fn(() => Promise.resolve({ ok: true as const, value: { accepted: true as const } }))
   const loadOlder = vi.fn(() => Promise.resolve())
-  const sessions = {
-    binding: (sessionId: SessionId) => ({
-      sessionId, session: { prompt, cancel, loadOlder },
-    }),
-    scopeOf,
-  } as unknown as SessionsService
-  if (withSessions) ctx.provide('sessions', sessions)
-  await ctx.plugin(ConversationService).await()
-  const root = ctx.get('conversation') as ConversationService
-  const scoped = ctx.plugin(() => {}).ctx.extend({ [SCOPE_TAG]: sid('s1') }).get('conversation') as ConversationService
-  return { root, scoped, prompt, cancel, loadOlder }
+  await runtime.sessions.add({
+    id: 's1',
+    session: { prompt, cancel, loadOlder },
+  })
+  // config.input is required (the apply shares its hub with the inject
+  // factories); the bench passes its own instance explicitly.
+  const fiber = runtime.ctx.plugin(ConversationService, {
+    input: new InputHub(runtime.ctx),
+  })
+  await fiber.await()
+  const root = runtime.ctx.get('conversation') as ConversationService
+  const scoped = runtime.sessions.scope('s1')!.get('conversation') as ConversationService
+  return { runtime, root, scoped, prompt, cancel, loadOlder }
 }
 
 describe('ConversationService', () => {
@@ -45,6 +38,7 @@ describe('ConversationService', () => {
     expect(b.prompt).toHaveBeenCalledWith([{ type: 'text', text: 'hello' }], 'steer')
     expect(b.cancel).toHaveBeenCalledOnce()
     expect(b.loadOlder).toHaveBeenCalledOnce()
+    await b.runtime.dispose()
   })
 
   it('folds Session business failures into callback rejections', async () => {
@@ -53,12 +47,21 @@ describe('ConversationService', () => {
     await expect(b.scoped.send('x', 'queue')).rejects.toThrow('conversation.send failed: agent-busy: busy')
     b.cancel.mockResolvedValueOnce({ ok: false, error: { code: 'internal', message: 'nope', details: {} } } as never)
     await expect(b.scoped.cancel()).rejects.toThrow('conversation.cancel failed: internal: nope')
+    await b.runtime.dispose()
   })
 
-  it('fails loudly from the root scope or without SessionsService', async () => {
+  it('fails loudly from the root scope, on an unbound session, or without SessionsService', async () => {
     const b = await bench()
     await expect(b.root.send('x', 'queue')).rejects.toThrow(/requires a session scope/)
-    const missing = await bench(false)
-    await expect(missing.root.send('x', 'queue')).rejects.toThrow(/sessions service unavailable/)
+    await b.runtime.sessions.remove('s1')
+    await expect(b.scoped.send('x', 'queue')).rejects.toThrow(/resolved no binding/)
+    await b.runtime.dispose()
+    // No SessionsService at all: a bare context (the runtime always provides one).
+    const bare = new Context()
+    await bare.plugin(ConversationService, {
+      input: new InputHub(bare),
+    }).await()
+    const orphan = bare.get('conversation') as ConversationService
+    await expect(orphan.send('x', 'queue')).rejects.toThrow(/sessions service unavailable/)
   })
 })

packages/client/ui-layout/src/client/index.ts

@@ -17,14 +17,16 @@ import { ThemePresenter } from './theme-presenter.ts'
 
 // Contract surface only (export-convergence rule: cross-package consumers
 // keep a symbol exported; test-only/package-internal symbols live off /src).
-// LayoutService: the ctx.layout service class (consumers type against it).
+// ILayout: the ctx.layout face consumers and test fakes type against.
 // OwnerShare contracts below are the render-side halves registrants compose
 // against; the frame components and the store factory are package-internal.
 export { LayoutService } from './service.ts'
+export type { ILayout } from './service.ts'
 
 declare module 'cordis' {
   interface Context {
-    layout: LayoutService
+    /** The outward face only; the concrete service stays inside this plugin. */
+    layout: import('./service.ts').ILayout
   }
 }
 

packages/client/ui-layout/src/client/service.ts

@@ -14,8 +14,23 @@ import type { createLayoutStore } from './stores.ts'
 /** The layout store's bound action set (framework-baked, draft params peeled). */
 export type PanelActions = BoundActions<ReturnType<typeof createLayoutStore>>
 
+/**
+ * The outward layout face (`ctx.layout`): the panel transitions other
+ * plugins may trigger — and exactly what a test fake must supply. The
+ * attachPanels wiring hook stays on the concrete class (root-entry assembly
+ * only).
+ */
+export interface ILayout {
+  /** Toggle the sidebar panel (closed ⟷ contract default width). */
+  toggleSidebar(): void
+  /** Open the details panel (no-op when already open). */
+  openDetails(): void
+  /** Close the details panel. */
+  closeDetails(): void
+}
+
 /** Cross-plugin panel-action face (ctx.layout). */
-export class LayoutService {
+export class LayoutService implements ILayout {
   #panels: PanelActions | undefined
 
   /**

packages/client/ui-sidebar/package.json

@@ -47,6 +47,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",

packages/client/ui-sidebar/tests/__snapshots__/sidebar-snapshot.spec.tsx.snap

@@ -0,0 +1,131 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`sidebar shell snapshots > renders the collapsed rail after the crossfade settles, in place 1`] = `
+<div
+  data-slot="sidebar"
+>
+  <div
+    class="root collapsed railIn"
+    style=""
+  >
+    <div
+      class="logoRow"
+    >
+      <button
+        aria-label="Open sidebar"
+        class="iconButton toggle"
+        type="button"
+      >
+        <svg
+          aria-hidden="true"
+          class="railFish"
+          data-content="965fe321"
+          fill="none"
+          height="17.6580310880829"
+          viewBox="0 0 23.16 17.04"
+          width="24"
+        />
+        <svg
+          class="panelIcon"
+          data-content="35f95b0c"
+          fill="none"
+          height="18"
+          viewBox="0 0 16 16"
+          width="18"
+          xmlns="http://www.w3.org/2000/svg"
+        />
+      </button>
+    </div>
+    <button
+      aria-label="New session"
+      class="newSession"
+      type="button"
+    >
+      <svg
+        data-content="c0ce4dcc"
+        fill="none"
+        height="18"
+        viewBox="0 0 16 16"
+        width="18"
+        xmlns="http://www.w3.org/2000/svg"
+      />
+    </button>
+    <div
+      class="regionArea"
+    />
+    <div
+      class="footArea"
+    />
+  </div>
+</div>
+`;
+
+exports[`sidebar shell snapshots > renders the expanded column (wordmark, capsule, empty holes) 1`] = `
+<div
+  data-slot="sidebar"
+>
+  <div
+    class="root"
+    style="width: 300px;"
+  >
+    <div
+      class="logoRow"
+    >
+      <button
+        aria-label="New session"
+        class="brand wide"
+        type="button"
+      >
+        <svg
+          aria-hidden="true"
+          data-content="951274b9"
+          fill="none"
+          height="24"
+          viewBox="0 0 182 24"
+          width="182"
+        />
+      </button>
+      <button
+        aria-label="Collapse sidebar"
+        class="iconButton toggle"
+        type="button"
+      >
+        <svg
+          class="panelIcon"
+          data-content="35f95b0c"
+          fill="none"
+          height="16"
+          viewBox="0 0 16 16"
+          width="16"
+          xmlns="http://www.w3.org/2000/svg"
+        />
+      </button>
+    </div>
+    <button
+      aria-label="New session"
+      class="newSession"
+      type="button"
+    >
+      <svg
+        data-content="c0ce4dcc"
+        fill="none"
+        height="14"
+        viewBox="0 0 16 16"
+        width="14"
+        xmlns="http://www.w3.org/2000/svg"
+      />
+      <span
+        class="newSessionLabel wide"
+      >
+        New Session
+      </span>
+    </button>
+    <div
+      class="regionArea"
+    />
+    <div
+      class="footArea"
+    />
+  </div>
+</div>
+`;

packages/client/ui-sidebar/tests/sidebar-snapshot.spec.tsx

@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+/**
+ * Local DOM snapshots of the sidebar shell through the real assembly path:
+ * SlotTestRuntime mounts the package apply on its own fiber, the auto frame
+ * supplies the layout's owner share at the render site, and the snapshot
+ * captures exactly the 'sidebar' slot's output (CSS-module class names
+ * folded to their semantic locals by the runtime's serializer). The child
+ * holes (sidebar.workspaces / sidebar.settings) have no registrant here, so
+ * the snapshots pin the shell chrome itself.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, waitFor } from '@testing-library/react'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import { apply, inject } from '@deepseek-ai/dsh-client-ui-sidebar/client'
+
+afterEach(cleanup)
+
+async function bench() {
+  const runtime = await SlotTestRuntime.create()
+  runtime.provide('layout', { toggleSidebar: vi.fn() })
+  await runtime.declare({ 'sidebar': { kind: 'single', scope: 'root' } })
+  await runtime.mount({ inject: [...inject], apply })
+  return runtime
+}
+
+describe('sidebar shell snapshots', () => {
+  it('renders the expanded column (wordmark, capsule, empty holes)', async () => {
+    const runtime = await bench()
+    const slot = runtime.renderSlot('sidebar', { collapsed: false, width: 300 })
+    // Wordmark + capsule both start a session in the expanded state.
+    expect(slot.view.getAllByRole('button', { name: 'New session' })).toHaveLength(2)
+    expect(slot.container).toMatchSnapshot()
+    await runtime.dispose()
+  })
+
+  it('renders the collapsed rail after the crossfade settles, in place', async () => {
+    const runtime = await bench()
+    const slot = runtime.renderSlot('sidebar', { collapsed: false, width: 300 })
+    const shell = slot.container.firstElementChild
+    slot.update({ collapsed: true, width: 56 })
+    // The wide content (wordmark shortcut) unmounts at the 150ms settle;
+    // only the rail's capsule remains a New-session button.
+    await waitFor(() => {
+      expect(slot.view.getAllByRole('button', { name: 'New session' })).toHaveLength(1)
+    })
+    expect(slot.container).toMatchSnapshot()
+    // Same tree position: the owner flip re-rendered the shell in place.
+    expect(slot.container.firstElementChild).toBe(shell)
+    await runtime.dispose()
+  })
+})

packages/client/ui-slash/src/client/index.ts

@@ -24,7 +24,8 @@ export type { SlashServiceContract } from './contract.ts'
 
 declare module 'cordis' {
   interface Context {
-    slash: SlashService
+    /** The outward face only; the concrete service stays inside this plugin. */
+    slash: import('./contract.ts').SlashServiceContract
   }
 }
 

packages/client/ui-slash/src/client/service.ts

@@ -7,7 +7,7 @@
  */
 import { Service } from 'cordis'
 import type { Context } from 'cordis'
-import type { ClientContext, SessionId, SessionsService } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ClientContext, ISessions, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SlashSource } from '../types.ts'
 import { SlashController } from './controller.ts'
 import type { SlashServiceContract } from './contract.ts'
@@ -99,7 +99,7 @@ export class SlashService extends Service implements SlashServiceContract {
     return controller
   }
 
-  private sessions(): SessionsService {
+  private sessions(): ISessions {
     const sessions = this.ctx.get('sessions')
     if (sessions === undefined) throw new Error('ui-slash: sessions service unavailable')
     return sessions

packages/client/web/package.json

@@ -31,6 +31,7 @@
   "devDependencies": {
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",

packages/client/web/tests/app-shell.spec.tsx

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+/**
+ * App-shell assembly plugin on the real machinery: bare Context + production
+ * SlotsService + the test-runtime session/workspace doubles. Deliberately NOT
+ * mounted through SlotTestRuntime — its create() installs the capturing
+ * renderer and install() is boot-once; app-shell IS the production installer,
+ * so this bench hands it the uninstalled service exactly as boot does.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, render } from '@testing-library/react'
+import { Context } from 'cordis'
+import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
+import { TestSessions, TestWorkspaces } from '@deepseek-ai/dsh-client-test-runtime'
+import type { Stabilizer } from '@deepseek-ai/dsh-client-test-runtime'
+import * as AppShell from '@deepseek-ai/dsh-client-web/src/app-shell.ts'
+
+afterEach(cleanup)
+
+const stabilize: Stabilizer = async (fn) => { await act(async () => { await fn() }) }
+
+async function bench() {
+  const ctx = new Context()
+  await ctx.plugin(SlotsService).await()
+  const slots = ctx.get('slots') as SlotsService
+  ctx.provide('sessions', new TestSessions(stabilize, ctx))
+  ctx.provide('workspaces', new TestWorkspaces(stabilize))
+  ctx.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+  const fiber = ctx.plugin({ inject: [...AppShell.inject], apply: AppShell.apply })
+  await fiber.await()
+  return { ctx, slots, fiber }
+}
+
+describe('app-shell assembly plugin', () => {
+  it('installs the renderer and provides the assembled appShell face', async () => {
+    const { ctx, slots } = await bench()
+    slots.register({ name: 'root' }, () => <div data-testid="root-probe" />)
+    const shell = ctx.get('appShell')
+    expect(shell).toBeDefined()
+    const view = render(<>{shell!.renderApp()}</>)
+    expect(view.getByTestId('root-probe')).toBeTruthy()
+  })
+
+  it('assembles once: repeated renderApp calls reuse the built closure', async () => {
+    const { ctx, slots } = await bench()
+    slots.register({ name: 'root' }, () => <div data-testid="root-probe" />)
+    const shell = ctx.get('appShell')!
+    const first = render(<>{shell.renderApp()}</>)
+    expect(first.getByTestId('root-probe')).toBeTruthy()
+    first.unmount()
+    // Second call rides the cached closure (renderApp ??=) and still renders.
+    const second = render(<>{shell.renderApp()}</>)
+    expect(second.getByTestId('root-probe')).toBeTruthy()
+  })
+
+  it('fiber dispose retracts the service and uninstalls the renderer', async () => {
+    const { ctx, slots, fiber } = await bench()
+    await stabilize(() => fiber.dispose())
+    expect(ctx.get('appShell')).toBeUndefined()
+    expect(() => slots.renderSlot('root', {})).toThrow('not installed')
+  })
+})

packages/client/web/tests/app.spec.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+/**
+ * buildRenderApp on SlotTestRuntime: the fail-loud sessions precondition, the
+ * one ctx-level renderSlot('root') call, and the document-title projection
+ * arms over the real slot stack.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { Context } from 'cordis'
+import { SlotTestRuntime } from '@deepseek-ai/dsh-client-test-runtime'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import { buildRenderApp } from '@deepseek-ai/dsh-client-web/src/app.tsx'
+
+let runtime: SlotTestRuntime | undefined
+
+afterEach(async () => {
+  cleanup()
+  await runtime?.dispose()
+  runtime = undefined
+  document.title = ''
+})
+
+async function bench() {
+  runtime = await SlotTestRuntime.create()
+  await runtime.root.declare({}, () => <div data-testid="frame" />)
+  return { runtime, renderApp: buildRenderApp({ ctx: runtime.ctx }) }
+}
+
+describe('buildRenderApp', () => {
+  it('fails loud when the sessions service is unavailable', () => {
+    expect(() => buildRenderApp({ ctx: new Context() })).toThrow('sessions service unavailable')
+  })
+
+  it('renders the root slot tree through the one ctx-level renderSlot call', async () => {
+    const b = await bench()
+    const view = render(<>{b.renderApp()}</>)
+    expect(view.getByTestId('frame')).toBeTruthy()
+  })
+
+  it('projects the current session durable title and falls back to the product title', async () => {
+    document.title = 'Product'
+    const b = await bench()
+    render(<>{b.renderApp()}</>)
+    // No current session: the product title stands.
+    expect(document.title).toBe('Product')
+    await b.runtime.sessions.add({ id: 's1', summary: { title: 'First' } })
+    expect(document.title).toBe('First — Product')
+    await b.runtime.sessions.setCurrent(undefined)
+    expect(document.title).toBe('Product')
+    // A session without a durable title keeps the product title.
+    await b.runtime.sessions.add({ id: 's2' })
+    expect(document.title).toBe('Product')
+  })
+
+  it('a current id without a list row falls back (selection/list arbitration transient)', async () => {
+    document.title = 'Product'
+    const b = await bench()
+    await b.runtime.sessions.add({ id: 's1', summary: { title: 'First' } })
+    render(<>{b.renderApp()}</>)
+    expect(document.title).toBe('First — Product')
+    b.runtime.sessions.list.update((draft) => { draft.current = 'ghost' as SessionId })
+    await b.runtime.flush()
+    expect(document.title).toBe('Product')
+  })
+})

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -150,6 +150,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'async request(req: ApprovalRequest): Promise<ApprovalOutcome>',
         jsDoc: '/**\n * Ask the composed answerers to decide one readonly same-process request.\n * The service borrows the request, agent, session, and live signal directly.\n * The request requires an open turn because the audit pair must be enclosed\n * by the durable log\'s commit/replay boundary; an idle ask rejects before\n * appending anything. The answerer phase always produces an outcome: an\n * aborted signal yields `\'cancelled\'`, a missing or throwing answerer yields\n * `\'unavailable\'` (fail closed), and a rogue non-vocabulary return value is\n * normalized to `\'unavailable\'`. A failure that prevents either audit append\n * from committing still rejects because returning an unlogged decision would\n * violate the pair. Session contains post-commit observer failures, so an\n * authoritative append cannot reject the request or suppress its matching\n * audit event.\n * @param req - the pending decision (agent, tool identity, reason, signal).\n * @returns the closed outcome; `\'allowed-once\'` is the only grant.\n * @throws when no turn is open or either audit event fails before the session\n *   append commit point.\n */',
       },
+      {
+        signature: 'overrideOf(session: Session): ApprovalPolicy | undefined',
+        jsDoc: '/**\n * Read the session override without applying the configured default.\n * @param session - session whose log supplies the override.\n * @returns the last logged policy, or `undefined` without one.\n */',
+      },
     ],
   },
   {
@@ -498,6 +502,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy',
         jsDoc: '/**\n * Resolve the complete policy for one capability call. An approved explicit\n * mode outranks the session\'s last `sandbox/mode` event, which outranks the\n * deployment default. A session cwd is its workspace-write boundary; the\n * configured root is the fallback for agentless calls and sessions without a\n * cwd.\n * @param request - optional session and approved mode override.\n * @returns the fully resolved per-call mode and absolute workspace root.\n */',
       },
+      {
+        signature: 'overrideOf(session: Session): SandboxMode | undefined',
+        jsDoc: '/**\n * Read the session override without applying the deployment default.\n * @param session - session whose log supplies the override.\n * @returns the last logged mode, or `undefined` without one.\n */',
+      },
     ],
   },
   {
@@ -518,11 +526,15 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
-        jsDoc: '/**\n * Load a header and balanced contiguous log. A complete interrupted final\n * turn is preserved and durably closed with missing tool errors plus any open\n * step and turn boundaries; only a torn final record is discarded. Unknown\n * versions and corruption in the committed prefix reject. Implementations\n * MUST NOT crash-repair an identity still bound to a live Session: a balanced\n * live log may return with its stored header as a durable snapshot, while an\n * open live turn rejects.\n * A coordinator-backed cold load reserves the identity across storage awaits,\n * so concurrent publication of a same-id live Session rejects.\n * Returned events are detached, and every identified message is deeply\n * frozen; malformed identified messages reject before any stored event is returned.\n * @param id - the persisted session to reload.\n * @returns the header and a log ending on a balanced `turn/end`.\n */',
+        jsDoc: '/**\n * Load a header and balanced contiguous log. A complete interrupted final\n * turn is preserved and durably closed with missing tool errors plus any open\n * step and turn boundaries; only a torn final record is discarded. Unknown\n * versions and corruption in the committed prefix reject. Implementations\n * MUST NOT crash-repair an identity still bound to a live Session: a balanced\n * live log may return with its stored header as a durable snapshot, while an\n * open live turn rejects.\n * A coordinator-backed cold load reserves the identity across storage awaits,\n * so concurrent publication of a same-id live Session rejects.\n * Returned events are detached, and every identified message is deeply\n * frozen. Coordinator-backed implementations upgrade supported pre-identity\n * message events before validation; other malformed messages reject before\n * any stored event is returned.\n * @param id - the persisted session to reload.\n * @returns the header and a log ending on a balanced `turn/end`.\n */',
       },
       {
         signature: 'abstract inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
-        jsDoc: '/**\n * Inspect a header and its valid contiguous stored prefix without repairing\n * a torn tail, closing an interrupted turn, or publishing coordinator state.\n * This read is serialized with writes for the same id and returns detached\n * values with deeply frozen identified messages, so observers cannot mutate message\n * identity/content or backend-owned state. Malformed identified messages reject.\n * @param id - the persisted session to inspect.\n * @param signal - optional cancellation for queued and backend read work.\n * @returns the header and valid stored event prefix exactly as observed.\n */',
+        jsDoc: '/**\n * Inspect a header and its valid contiguous stored prefix without repairing\n * a torn tail, closing an interrupted turn, or publishing coordinator state.\n * This read is serialized with writes for the same id and returns detached\n * values with upgraded, deeply frozen identified messages, so observers\n * cannot mutate message identity/content or backend-owned state. Other\n * malformed messages reject.\n * @param id - the persisted session to inspect.\n * @param signal - optional cancellation for queued and backend read work.\n * @returns the header and valid stored event prefix exactly as observed.\n */',
+      },
+      {
+        signature: 'abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
+        jsDoc: '/**\n * Read the stored events from `fromSeq` onward — the read-from-seq\n * primitive for read models that resume from a watermark (e.g. a persisted\n * projection cache folding only the tail past its checkpoint). Like\n * {@link inspect} it is non-mutating and detached: no torn-tail truncation,\n * no synthetic closers, no coordinator-state publication; only events from\n * the valid contiguous stored prefix are returned, so a torn fragment never\n * reaches the caller. `fromSeq` at or beyond the stored prefix returns an\n * empty event list (never an error). Backends whose medium can seek by seq\n * (SQLite) read only the suffix; sequential media (JSONL, both encodings)\n * still parse the whole artifact and skip forward — the primitive bounds\n * what is RETURNED and refolded, not every backend\'s physical read.\n * @param id - the persisted session to read.\n * @param fromSeq - first event seq to include; a non-negative safe integer.\n * @param signal - optional cancellation for queued and backend read work.\n * @returns the header and the stored events with `seq >= fromSeq`.\n */',
       },
       {
         signature: 'abstract list(signal?: AbortSignal): Promise<SessionHeader[]>',
@@ -534,6 +546,24 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'sessionProjectionCache',
+    summary: 'The persisted projection cache service.',
+    methods: [
+      {
+        signature: 'cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined',
+        jsDoc: '/**\n * The zero-I/O listing read: whole values viewed straight from the stored\n * rows (version-matching keys only), each cut carried with its watermark\n * so a client value store can seed under its higher-seq-wins rule — as\n * stale as the last durable checkpoint but never wrong, and never from an\n * unrelated log (the caller\'s header is the identity witness). Fresher\n * paths (the history tail baseline, {@link coldSnapshot}) supersede these\n * values whenever a session is actually opened.\n * @param meta - the listed session\'s header (identity witness; no log read).\n * @returns the cut (`asOfSeq` = lowest served-row watermark), or\n *   `undefined` when no usable row exists for this lifecycle.\n */',
+      },
+      {
+        signature: 'async write(session: Session): Promise<void>',
+        jsDoc: '/**\n * Durably checkpoint one live session NOW (both mandatory points call\n * this; tests and carriers may too). The registry cut is snapshotted at\n * this boundary (states are live references), then the whole record is\n * replaced. NOT fail-soft — callers on the fail-soft paths contain it.\n * @param session - the live session to checkpoint.\n * @returns resolution after durability and event emission.\n */',
+      },
+      {
+        signature: 'async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>',
+        jsDoc: '/**\n * Cold-read one persisted session\'s projections with zero full-log load:\n * cached rows + a persistence `readFrom` tail from the registry\'s restore\n * floor, refolded by the registry and written back (fail-soft) so the next\n * cold read starts closer. A cache row invalidated by a shrunk log\n * (crash-repair truncation) triggers one full re-read from seq 0 — the\n * ladder\'s slow rung, still no crash. Rejects when the session has no\n * persisted log (`not found` from the persistence seam).\n * @param id - the persisted session to read.\n * @param signal - optional cancellation for the persistence reads.\n * @returns the snapshot cut at the stored log end.\n */',
+      },
+    ],
+  },
   {
     key: 'sessionProjections',
     summary: '`ctx.sessionProjections`: the projection unit table and its drive.',
@@ -550,6 +580,22 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'snapshot(session: Session): ProjectionSnapshot',
         jsDoc: '/**\n * One consistent cut over every registered unit for one session, read from\n * the watermark cache (missing cells fold lazily over the in-memory log).\n * Fully synchronous — every value and `asOfSeq` reflect the same log\n * position. Each value passes its unit\'s schema before leaving.\n * @param session - the session whose projection values are read.\n * @returns the snapshot; `values` is empty when no unit is registered.\n */',
       },
+      {
+        signature: 'checkpoint(session: Session): ProjectionCheckpoint',
+        jsDoc: '/**\n * State-level checkpoint of every registered unit for one session, read\n * from the watermark cache (missing cells fold lazily over the in-memory\n * log). This is the write side of the persisted projection cache: the\n * returned rows are the `(key → {ver, seq, val})` part of the durable\n * `(sessionId, key, ver, seq, val)`\n * rows. Every `val` is a DETACHED structured clone — never the live\n * cell reference: the watermark cache is this registry\'s authoritative\n * mutable state, and a caller reaching the live reference could corrupt\n * every subsequent snapshot and frame through it (plain JSON by the unit\n * contract, so the clone is total).\n * @param session - the session whose unit states are checkpointed.\n * @returns one row per registered key; empty when no unit is registered.\n */',
+      },
+      {
+        signature: 'restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined',
+        jsDoc: '/**\n * The stored seq a {@link restore} tail read over `checkpoint` must start\n * at: one event BELOW the lowest usable watermark (a row is usable when\n * its `ver` matches the live unit\'s `stateVersion`; an absent or mismatched row\n * pulls the floor to `0` — that key must refold the full log). The\n * one-below anchor is load-bearing: the tail then proves how far the\n * stored log still extends, so {@link restore} can detect a log that\n * shrank below a row\'s watermark (crash-repair truncation) instead of\n * serving the stale row as current — an empty tail read from the anchor\n * yields an end below every watermark and the restore rejects for a full\n * re-read.\n * @param checkpoint - persisted rows for one session (possibly stale or empty).\n * @returns the seq to hand the persistence `readFrom`, or `undefined`\n *   when no unit is registered (no read needed — {@link restore} would\n *   serve empty values regardless).\n */',
+      },
+      {
+        signature: 'viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>',
+        jsDoc: '/**\n * View a checkpoint\'s rows without any log read: for every registered\n * unit whose row\'s `ver` matches, serve the schema-validated\n * `view` of the stored state; mismatched or absent rows leave their key\n * absent (a cold or listing consumer treats it as not-yet-available and a\n * fuller read path refolds it). The zero-I/O rung of the read ladder —\n * values are as stale as their rows, never wrong.\n * @param checkpoint - persisted rows for one session (possibly stale or empty).\n * @returns whole values per key with a usable row; empty when none.\n */',
+      },
+      {
+        signature: 'restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }',
+        jsDoc: '/**\n * Cold read: fold every registered unit over a stored log suffix, seeding\n * each from its checkpoint row when usable — the one read recipe (cached\n * state + forward tail replay + `view`) applied without a live `Session`.\n * Call with the events returned by a persistence\n * `readFrom(id, restoreFloor(checkpoint))` and that same floor as\n * `baseSeq`; the floor\'s one-below anchor makes the supplied end honest,\n * so a shrunk log is detected here. A row is usable iff its\n * `ver` matches the live unit\'s `stateVersion`, it does not predate `baseSeq`\n * (`seq >= baseSeq - 1`), and it does not claim events past the\n * supplied end (`seq <= endSeq`); an unusable row is discarded\n * and its key refolds from `init` — which is only sound over the full\n * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads\n * from seq 0, e.g. after a crash-repair truncation shrank the log below\n * a row\'s watermark).\n * @param checkpoint - persisted rows for one session (possibly stale or empty).\n * @param events - the stored events with `seq >= baseSeq`, in seq order.\n * @param baseSeq - the seq `events` starts at (its first event\'s seq when non-empty).\n * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last\n *   supplied event\'s seq, `baseSeq - 1` for an empty tail) plus the\n *   refreshed checkpoint rows at that cut, ready for a durable write-back.\n */',
+      },
     ],
   },
   {
@@ -1855,6 +1901,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ProjectionChangeListener',
     declaration: 'export type ProjectionChangeListener = (session: Session, key: Extract<keyof SessionProjectionMap, string>, value: unknown, seq: number) => void;',
   },
+  {
+    name: 'ProjectionCheckpoint',
+    declaration: 'export type ProjectionCheckpoint = Record<string, ProjectionCheckpointRow>;',
+  },
+  {
+    name: 'ProjectionCheckpointRow',
+    declaration: 'export interface ProjectionCheckpointRow {\n    ver: number;\n    seq: number;\n    val: unknown;\n}',
+  },
   {
     name: 'ProjectionDefinition',
     declaration: 'export interface ProjectionDefinition<K extends keyof SessionProjectionMap, S> {\n    key: K;\n    schema: ZodType<SessionProjectionMap[K]>;\n    init(): S;\n    apply(state: S, event: SessionEvent): S;\n    view(state: S): SessionProjectionMap[K];\n    stateVersion: number;\n}',

packages/core/agent-loop/tests/resume.spec.ts

@@ -5,7 +5,7 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
@@ -77,6 +77,65 @@ function throwUnknown(value: unknown): never {
 }
 
 describe('the session-persistence Agent Note: AgentLoop factory create/resume', () => {
+  it('resumes a session persisted before messages gained identities', async () => {
+    const sessionId = SessionId('pre-identity-resume')
+    const first = await persistentHarness(new MockAdapter([]))
+    await first.ctx.sessionPersistence.create({
+      version: SESSION_FORMAT_VERSION,
+      id: sessionId,
+      createdAt: 1,
+    })
+    await first.ctx.sessionPersistence.append(sessionId, [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      {
+        type: 'user/message',
+        seq: 1,
+        time: 2,
+        data: { content: [{ type: 'text', text: 'old question' }], source: { kind: 'user' } },
+        surfaceOp: 'append',
+      },
+      { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
+      {
+        type: 'assistant/message',
+        seq: 3,
+        time: 4,
+        data: {
+          turn: 1,
+          step: 1,
+          content: [{ type: 'text', text: 'old answer' }],
+          provenance: { provider: 'mock', model: 'mock' },
+        },
+        surfaceOp: 'append',
+      },
+      { type: 'step/end', seq: 4, time: 5, data: { turn: 1, step: 1 } },
+      { type: 'turn/end', seq: 5, time: 6, data: { turn: 1, reason: { kind: 'completed' } } },
+    ] as unknown as SessionEvent[])
+    await first.ctx.fiber.dispose()
+
+    const ctx = await mountPersistentHarness(first.root, new MockAdapter([textResponse('new answer')]))
+    const handle = await ctx.agents.resume({
+      resumeSessionId: sessionId,
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    expect(handle.agent.session.deriveMessages()).toMatchObject([
+      { id: `legacy-message:${sessionId}:1`, role: 'user' },
+      { id: `legacy-message:${sessionId}:3`, role: 'assistant' },
+    ])
+
+    handle.agent.followup(createUserMessage({
+      content: [{ type: 'text', text: 'new question' }],
+      source: { kind: 'user' },
+    }))
+    await waitForIdle(ctx, handle.agent)
+    expect(handle.agent.session.deriveMessages()).toHaveLength(4)
+    expect(handle.agent.session.events.at(-1)).toMatchObject({
+      type: 'turn/end',
+      data: { reason: { kind: 'completed' } },
+    })
+    await handle.dispose()
+    await ctx.fiber.dispose()
+  })
+
   it('normalizes a non-Error resume publication failure for rollback and rethrows it', async () => {
     const sessionId = SessionId('unknown-resume-failure-s')
     const root = await persistSession(sessionId)

packages/core/agent/src/index.ts

@@ -63,16 +63,11 @@ export interface CreateAgentOptions {
     readonly delegationDepth?: number
   }
   /**
-   * Seed events to reconstruct the child session's log from (the fork lineage
-   * primitive). When present, the factory creates the session with this event
-   * prefix so `deriveMessages()`/`lastTurnNumber` continue from it — used by the
-   * in-process FORK subagent backend to seed a child with a balanced
-   * completed-turn prefix of the parent's log. The prefix MUST be contiguous
-   * from seq 0, carry only lossless-JSON data, and be balanced (no open
-   * turn/step, no dangling tool-call), or the session constructor (and the
-   * dev-mode invariants replay) reject it. The factory passes the raw seed to
-   * the session's durable validator/snapshot boundary. Absent for a fresh
-   * (spawn) child.
+   * Initial replay/fork history. A fork supplies a balanced completed-turn
+   * prefix of the parent's log. The complete seed must be contiguous from seq
+   * 0, carry only lossless-JSON data, and contain no open turn/step or dangling
+   * tool call. The factory passes it to the session's durable
+   * validator/snapshot boundary before publication.
    */
   readonly seed?: readonly SessionEvent[]
   /** Per-agent options (model, …). */

packages/core/session/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/session/README.md
-README.md: 40516d12180de9c30efd40fdffa873da20ddacb3
-README.zh.md: 43842643a3434c741f219f7b6c26622cddfae8e7
+README.md: a9b6905dcf2b8ef1f75595e567273f7a3150a412
+README.zh.md: f1a5e97e32d1ad1abcd6ad96e6c621af9972e989

packages/core/session/README.md

@@ -142,5 +142,5 @@ Logging causes no invalidation, and exact reconstruction preserves request-prefi
 
 - **Session branching/tree** (pi-style entry tree) — deferred unless needed beyond boundary-based `fork()`.
 - **`fork()` cuts only at stable boundaries of live sessions** — the selected prefix must end outside an open turn and the source must be in the store; forking a persisted-but-unloaded session is excluded from the [fork API](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md).
-- **`SESSION_FORMAT_VERSION` stays pinned at `0`** — pre-release, no compatibility implied: a backend rejects any other version, and no migration path exists until the first release ([policy](../../../AGENTS.md)).
+- **`SESSION_FORMAT_VERSION` stays pinned at `0`** — pre-release, no broad compatibility implied: `Session` accepts only current seed shapes and a backend rejects any other version. Narrow storage import upgrades belong to the persistence boundary ([policy](../../../AGENTS.md), [pre-identity message recovery](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)).
 - **`TurnEndReasonMap` omits the ACP-named `refusal` / `max_turn_requests` variants** — producer-gated: they land when an adapter or the loop first emits them.

packages/core/session/README.zh.md

@@ -142,5 +142,5 @@
 
 - **会话分支／树**（pi 风格条目树）：除非需要超越基于边界的 `fork()` 能力，否则暂缓。
 - **`fork()` 仅在实时会话的稳定边界处切分**：所选前缀结束时不得有开放轮次，且源会话必须位于存储中；[fork API](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) 不支持对已持久化但未加载的会话进行 fork。
-- **`SESSION_FORMAT_VERSION` 固定为 `0`**：预发布阶段不承诺兼容性；后端会拒绝其他任何版本，首次发布前不提供迁移路径（[政策](../../../AGENTS.md)）。
+- **`SESSION_FORMAT_VERSION` 固定为 `0`**：预发布阶段不承诺广泛兼容性；`Session` 只接受当前 seed 形状，后端会拒绝其他任何版本。范围受限的存储导入升级应由持久化边界负责（[政策](../../../AGENTS.md)、[消息标识机制引入前的消息恢复](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。
 - **`TurnEndReasonMap` 不含 ACP（Agent Client Protocol）命名的 `refusal`／`max_turn_requests` 变体**：受生产方约束；只有当适配器或循环首次产生这些变体时才加入。

packages/core/session/src/types.ts

@@ -72,7 +72,7 @@ export interface SessionHeader {
  * store folds into a {@link SessionHeader}.
  */
 export interface CreateSessionOptions {
-  /** Events to seed the new session with (replay/fork). */
+  /** Initial replay or fork history supplied at construction. */
   readonly seed?: readonly SessionEvent[]
   /**
    * Storage metadata read once before publication. `seedLength` is explicit

packages/host/apiproxy/package.json

@@ -47,6 +47,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
     "@deepseek-ai/dsh-skill": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "@deepseek-ai/dsh-user-approval": "workspace:^",

packages/host/apiproxy/src/api-proxy.ts

@@ -30,6 +30,8 @@ import type {
 } from './api/index.ts'
 // Type-only: resolves `ctx.get('sessionProjections')` to the projection registry.
 import type {} from '@deepseek-ai/dsh-session-projection'
+// Type-only: resolves `ctx.get('sessionProjectionCache')` (the cold listing column).
+import type {} from '@deepseek-ai/dsh-session-projection-cache'
 // Type-only edges: resolve `ctx.get('commands')`, the `commands/change` event, and `ctx.get('skills')`.
 import type {} from '@deepseek-ai/dsh-commands'
 import type {} from '@deepseek-ai/dsh-skill'
@@ -309,6 +311,28 @@ function projectionsFor(ctx: Context, agent: Agent): SessionProjectionsBlock | u
   return registry.snapshot(agent.session)
 }
 
+/**
+ * The projection baseline of one session.list row, fail-soft: attached
+ * sessions cut the registry's live watermark cache; cold sessions view the
+ * persisted projection cache's identity-checked stored rows (zero log loads
+ * either way — the listing use case the cache exists for). The block shape
+ * (values + asOfSeq) matches the history tail's, so a client seeds its
+ * value store under the same higher-seq-wins rule. Any failure — and an
+ * empty value set — yields an absent block: a listing without projections
+ * is degraded, never broken.
+ */
+function listProjectionsFor(ctx: Context, meta: SessionHeader, session: Session | undefined): SessionProjectionsBlock | undefined {
+  try {
+    const block = session !== undefined
+      ? ctx.get('sessionProjections')?.snapshot(session)
+      : ctx.get('sessionProjectionCache')?.cachedSnapshot(meta)
+    return block !== undefined && Object.keys(block.values).length > 0 ? block : undefined
+  } catch (error) {
+    ctx.logger.warn(`session.list: projection column for "${meta.id}" failed (serving the row without it): ${String(error)}`)
+    return undefined
+  }
+}
+
 /**
  * Thrown by the cold-resume path when the id names no servable session
  * (absent from the store, or a pre-project legacy log without a cwd).
@@ -666,13 +690,25 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       async list(request) {
         const items = ctx.sessions.list().map((session) => {
           const agent = ctx.agents.get(session.id)
-          return summarize(session, agent?.status === 'running')
+          const projections = listProjectionsFor(ctx, session.header, session)
+          return {
+            ...summarize(session, agent?.status === 'running'),
+            ...projections === undefined ? {} : { projections },
+          }
         })
         const attached = new Set(items.map(item => item.sessionId))
         const persistence = ctx.get('sessionPersistence')
         if (persistence !== undefined) {
           const cold = (await persistence.list()).filter(meta => !attached.has(meta.id) && meta.cwd !== undefined)
-          items.push(...await Promise.all(cold.map(meta => summarizeCold(persistence, meta))))
+          items.push(...await Promise.all(cold.map(async (meta) => {
+            // Cold rows read the persisted projection cache only — never a
+            // log load; a session without a cache row simply has no column.
+            const projections = listProjectionsFor(ctx, meta, undefined)
+            return {
+              ...await summarizeCold(persistence, meta),
+              ...projections === undefined ? {} : { projections },
+            }
+          })))
         }
         items.sort((a, b) => b.updatedAt - a.updatedAt)
         return ok(request, { items })

packages/host/apiproxy/src/api/sessions.schema.ts

@@ -37,7 +37,7 @@ export const sessionEventSchema = z.object({
   surfaceOp: z.unknown().optional(),
 }) as unknown as z.ZodType<SessionEvent>
 
-/** SessionSummary row of session.list. */
+/** SessionSummary row of session.list (`projections` reuses the history block's shape and schema). */
 export const sessionSummarySchema = z.object({
   sessionId: sessionIdSchema,
   updatedAt: z.number(),
@@ -45,7 +45,8 @@ export const sessionSummarySchema = z.object({
   blank: z.boolean(),
   parentSessionId: sessionIdSchema.optional(),
   cwd: z.string().optional(),
-}) satisfies z.ZodType<Wire<SessionSummary>>
+  projections: z.lazy(() => sessionProjectionsBlockSchema).optional(),
+}) as unknown as z.ZodType<Wire<SessionSummary>>
 
 /** session.list request payload (cursor is a reserved seat, unimplemented in v1). */
 export const sessionListRequestSchema = z.object({
@@ -53,9 +54,9 @@ export const sessionListRequestSchema = z.object({
 }) satisfies z.ZodType<Wire<RequestPayload<'session.list'>>>
 
 /** session.list response value. */
-export const sessionListValueSchema = z.object({
+export const sessionListValueSchema: z.ZodType<Wire<ResponseValue<'session.list'>>> = z.object({
   items: z.array(sessionSummarySchema),
-}) satisfies z.ZodType<Wire<ResponseValue<'session.list'>>>
+})
 
 /** session.create request payload (at most one of workspaceId / cwd). */
 export const sessionCreateRequestSchema = z.object({

packages/host/apiproxy/src/api/sessions.ts

@@ -145,6 +145,18 @@ export interface SessionSummary {
   parentSessionId?: SessionId
   /** Session working directory (header.cwd passthrough); absent when unrecorded. */
   cwd?: string
+  /**
+   * Projection baseline for this row, with zero log loads: attached sessions
+   * read the registry's live watermark cut; cold sessions read the persisted
+   * projection cache's stored rows — as stale as that session's last durable
+   * checkpoint (`asOfSeq` says exactly how stale), never wrong, and directly
+   * seedable into the client's per-session value store under its
+   * higher-seq-wins rule (a list baseline can never overwrite a newer push
+   * frame). Absent when no value is available (no registry, no cache row for
+   * a cold session, or a fail-soft cache read miss); a listing client treats
+   * absence as "no title yet", exactly like a blank session.
+   */
+  projections?: SessionProjectionsBlock
 }
 
 /** Session-domain unary methods (the map keys session.* of RpcMethodMap). */

packages/host/apiproxy/tests/api-proxy-projections.spec.ts

@@ -13,7 +13,7 @@ import { z } from 'zod'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { Session } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
@@ -125,6 +125,82 @@ describe('session.history projections block', () => {
   })
 })
 
+describe('session.list projections column', () => {
+  it('serves attached rows from the live registry cut, watermarked for client seeding', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register(lastUserUnit())
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row?.projections?.values['test/last-user']).toEqual({ text: 'm0' })
+    expect(row?.projections?.asOfSeq).toBe(session.seq - 1)
+  })
+
+  it('omits the column entirely when no registry is mounted', async () => {
+    const { ctx, session } = await harness(false)
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+
+  it('serves cold rows from the persisted projection cache with zero log loads', async () => {
+    const { ctx } = await harness(true)
+    const coldId = SessionId('session-cold-listing')
+    const load = () => { throw new Error('list must not load event logs') }
+    ctx.provide('sessionPersistence', {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
+      locate: () => undefined,
+      load,
+      inspect: load,
+      readFrom: load,
+    } as never)
+    ctx.provide('sessionProjectionCache', {
+      // The carrier hands the listed header through as the identity witness.
+      cachedSnapshot: (meta: { id: unknown; createdAt: number }) =>
+        (meta.id === coldId && meta.createdAt === 5
+          ? { asOfSeq: 7, values: { 'test/last-user': { text: 'cached' } } }
+          : undefined),
+    } as never)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === coldId)
+    expect(row?.running).toBe(false)
+    expect(row?.projections).toEqual({ asOfSeq: 7, values: { 'test/last-user': { text: 'cached' } } })
+  })
+
+  it('cold rows without a cache plugin (or without a stored row) just lack the column', async () => {
+    const { ctx } = await harness(true)
+    const coldId = SessionId('session-cold-uncached')
+    ctx.provide('sessionPersistence', {
+      list: async () => [{ version: 0, id: coldId, createdAt: 5, cwd: '/tmp' }],
+      locate: () => undefined,
+    } as never)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === coldId)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+
+  it('a throwing column read degrades that row, never the listing', async () => {
+    const { ctx, session } = await harness(true)
+    ctx.sessionProjections.register({
+      ...lastUserUnit(),
+      view: () => { throw new Error('unit exploded') },
+    })
+    seedMessages(session, 1)
+    const response = await api(ctx).sessions.list(request({}))
+    if (!response.result.ok) throw new Error('unreachable')
+    const row = response.result.value.items.find(item => item.sessionId === session.id)
+    expect(row).toBeDefined()
+    expect(row !== undefined && 'projections' in row).toBe(false)
+  })
+})
+
 describe('session/projection push frame', () => {
   /** Drain frames until `count` session/projection frames arrived. */
   async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: number, abort: AbortController): Promise<MuxFrame[]> {

packages/host/apiproxy/tsconfig.json

@@ -35,6 +35,9 @@
     {
       "path": "../../session-projection/session-projection"
     },
+    {
+      "path": "../../session-projection/session-projection-cache"
+    },
     {
       "path": "../../skill/skill"
     },

packages/sandbox/sandbox-policy/src/index.ts

@@ -100,10 +100,19 @@ export class SandboxPolicyService extends Service {
   resolve(request: SandboxPolicyRequest = {}): SandboxExecutionPolicy {
     const { session } = request
     return {
-      mode: request.mode ?? (session === undefined ? undefined : effectiveSandboxMode(session.events)) ?? this.defaultMode,
+      mode: request.mode ?? (session === undefined ? undefined : this.overrideOf(session)) ?? this.defaultMode,
       workspaceRoot: resolveWorkspaceRoot(session?.header.cwd ?? this.workspaceRoot),
     }
   }
+
+  /**
+   * Read the session override without applying the deployment default.
+   * @param session - session whose log supplies the override.
+   * @returns the last logged mode, or `undefined` without one.
+   */
+  overrideOf(session: Session): SandboxMode | undefined {
+    return effectiveSandboxMode(session.events)
+  }
 }
 
 export default SandboxPolicyService

packages/sandbox/sandbox-policy/src/session-mode.ts

@@ -27,11 +27,14 @@ declare module '@deepseek-ai/dsh-session' {
      * The session's sandbox mode was switched — log-only (like `approval/*`;
      * NOT a surface event, carries no `surfaceOp`): durable and replayable,
      * never in the model transcript. The LAST such event is the session's
-     * override ({@link effectiveSandboxMode}); who asked for it is derivable
-     * from position (an event after the log's last `request/header*` was a
-     * runtime switch by the user; see the tool layer's narrator).
+     * override ({@link effectiveSandboxMode}). `source: 'delegation'` marks
+     * an override seeded into a child; an absent source is a runtime switch.
      */
-    'sandbox/mode': { mode: SandboxMode }
+    'sandbox/mode': {
+      mode: SandboxMode
+      /** Marks an override seeded into a child at delegation. */
+      source?: 'delegation'
+    }
   }
 }
 

packages/sandbox/sandbox-policy/tests/policy.spec.ts

@@ -63,6 +63,8 @@ describe('SandboxPolicyService', () => {
       mode: 'read-only',
       workspaceRoot: resolve('/projects/second'),
     })
+    expect(ctx.sandboxPolicy.overrideOf(first)).toBeUndefined()
+    expect(ctx.sandboxPolicy.overrideOf(second)).toBe('read-only')
     expect(ctx.sandboxPolicy.resolve()).toEqual({
       mode: 'workspace-write',
       workspaceRoot: resolve('/fallback'),

packages/session-persistence/session-checkpoint-policy/tests/session-checkpoint-policy.spec.ts

@@ -22,6 +22,9 @@ class TestPersistence extends SessionPersistence {
   inspect(_id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     return Promise.reject(new Error('not used'))
   }
+  readFrom(_id: SessionId, _fromSeq: number): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return Promise.reject(new Error('not used'))
+  }
   list(): Promise<SessionHeader[]> { return Promise.resolve([]) }
   listSnapshots(): Promise<never[]> { return Promise.resolve([]) }
 }

packages/session-persistence/session-persistence-jsonl/src/format.ts

@@ -64,6 +64,9 @@ export function toHeaderLine(header: SessionHeader): HeaderLine {
  * @returns the header, absent optional fields omitted.
  */
 export function fromHeaderLine(line: HeaderLine): SessionHeader {
+  if (Object.hasOwn(line, 'sandboxMode') || Object.hasOwn(line, 'approvalPolicy')) {
+    throw new Error('session header uses retired policy baseline fields')
+  }
   return {
     version: line.version,
     id: line.id,

packages/session-persistence/session-persistence-jsonl/src/index.ts

@@ -134,6 +134,12 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
     return this.coordinator.inspect(id, signal)
   }
 
+  // JSONL is sequential media: no loadStoredFrom hook, so the coordinator
+  // parses the stored prefix (both encodings) and skips forward to fromSeq.
+  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.readFrom(id, fromSeq, signal)
+  }
+
   // One method serves both public `list` and the backend hook; delegating it to
   // the coordinator would call this hook recursively.
 

packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts

@@ -1023,6 +1023,12 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     expect(ids).toContain('big')
   })
 
+  it.each(['sandboxMode', 'approvalPolicy'] as const)('rejects the retired %s header field', (field) => {
+    const line = { ...toHeaderLine(meta('retired-policy-header')), [field]: 'read-only' }
+    expect(() => scanLog(Buffer.from(`${JSON.stringify(line)}\n`)))
+      .toThrow(/retired policy baseline fields/)
+  })
+
   it('list rejects a header whose cwd does not identify its physical log', async () => {
     const m = meta('misplaced', '/stored')
     await ctx.sessionPersistence.create(m)

packages/session-persistence/session-persistence-sqlite/src/index.ts

@@ -16,7 +16,7 @@ import { dirname, resolve } from 'node:path'
 import {
   SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
   type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
-  type StoredPrefix,
+  type StoredPrefix, type StoredSuffix,
 } from '@deepseek-ai/dsh-session-persistence'
 import type { SessionEvent, SurfaceEventType, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
@@ -161,6 +161,10 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     return this.coordinator.inspect(id, signal)
   }
 
+  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.readFrom(id, fromSeq, signal)
+  }
+
   // One method serves both public `list` and the backend hook; delegating it to
   // the coordinator would call this hook recursively.
 
@@ -171,6 +175,26 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     return this.readPrefix(id, signal)
   }
 
+  /**
+   * Seek-capable suffix read: SQL selects `seq >= fromSeq` directly, so the
+   * read scales with the suffix, not the log. Torn rows past the preserved
+   * region are dropped, never repaired (non-mutating read).
+   */
+  async loadStoredFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined> {
+    signal?.throwIfAborted()
+    await this.ready
+    signal?.throwIfAborted()
+    const row = this.rowFor(id)
+    if (row === undefined) return undefined
+    const meta = rowToMeta(row)
+    const eventRows = this.db
+      .prepare('SELECT seq, type, time, data, source_event_seqs, surface_op FROM events WHERE session_id = ? AND seq >= ? ORDER BY seq')
+      .all(id, fromSeq) as unknown as EventRow[]
+    signal?.throwIfAborted()
+    const { preserved } = scanRows(eventRows, fromSeq)
+    return { meta, events: preserved }
+  }
+
   /**
    * Read a session's row + ordered events into a {@link StoredPrefix}. The
    * torn-tail marker is the seq from which a never-committed tail must be deleted

packages/session-persistence/session-persistence-sqlite/src/schema.ts

@@ -17,7 +17,7 @@ import type { SessionEvent, SessionId, SessionHeader, SurfaceOp } from '@deepsee
  * layout; orthogonal to a session's own `version` (which versions the EVENT
  * vocabulary, stored per session in the `sessions` row).
  */
-export const SCHEMA_VERSION = 10
+export const SCHEMA_VERSION = 12
 
 /** SQLite application id protecting unrelated databases from persistence writes. */
 export const SESSION_PERSISTENCE_SQLITE_APPLICATION_ID = 0x44534850
@@ -213,10 +213,12 @@ export function rowToEvent(row: EventRow): SessionEvent {
  * the committed region rejects.
  *
  * @param rows - one session's event rows, ordered by seq ascending.
+ * @param base - the seq the first row is expected to carry; `0` for a whole
+ *   log, the requested `fromSeq` for a suffix read (`loadStoredFrom`).
  * @returns the preserved event prefix, plus `tornFrom` — the seq the physical
  *   delete starts at — when a torn tail exists.
  */
-export function scanRows(rows: readonly EventRow[]): { preserved: SessionEvent[]; tornFrom?: number } {
+export function scanRows(rows: readonly EventRow[], base = 0): { preserved: SessionEvent[]; tornFrom?: number } {
   // Pass 1: parse each row's data; a row whose data is not valid JSON is a hole.
   // (The seq/type COLUMNS are always present even when `data` is corrupt.)
   interface Parsed { ok: boolean; event?: SessionEvent }
@@ -244,8 +246,8 @@ export function scanRows(rows: readonly EventRow[]): { preserved: SessionEvent[]
       if (i <= lastTurnEnd) throw new Error(`corrupt session log: unparsable committed event at seq ${rows[i]?.seq}`)
       break // torn tail fragment after the last turn/end — stop, tolerate
     }
-    if (p.event.seq !== i) {
-      if (i <= lastTurnEnd) throw new Error(`corrupt session log: seq gap in committed region (expected ${i}, got ${p.event.seq})`)
+    if (p.event.seq !== base + i) {
+      if (i <= lastTurnEnd) throw new Error(`corrupt session log: seq gap in committed region (expected ${base + i}, got ${p.event.seq})`)
       break // gap after the last turn/end — torn tail, stop
     }
     preserved.push(p.event)
@@ -253,5 +255,5 @@ export function scanRows(rows: readonly EventRow[]): { preserved: SessionEvent[]
 
   // Any rows past the preserved prefix are a never-committed torn tail; their
   // first seq is the deletion point for load's physical repair.
-  return preserved.length < rows.length ? { preserved, tornFrom: preserved.length } : { preserved }
+  return preserved.length < rows.length ? { preserved, tornFrom: base + preserved.length } : { preserved }
 }

packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts

@@ -609,7 +609,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
   })
 
   it('exposes the schema version constant', () => {
-    expect(SCHEMA_VERSION).toBe(10)
+    expect(SCHEMA_VERSION).toBe(12)
   })
 
   it('keeps the revision stable for an empty repair hook', async () => {

packages/session-persistence/session-persistence/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session-persistence/session-persistence/README.md
-README.md: 08d8adac8040747a6dac01dbc41525073f17060c
-README.zh.md: 7676f27a1aa934eb3472e1b32b9ecd55d460fb63
+README.md: a8a4f14c8613a7e51bcf467e816b7f7bdb7ea80b
+README.zh.md: 369e8a01b8ac411ed9acfbac86b9b34db8037c1f

packages/session-persistence/session-persistence/README.md

@@ -13,8 +13,9 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 | `locate(meta): SessionLocation \| undefined` | Resolve an absolute per-session artifact target without I/O or materialization. Backends without an independent local artifact return `undefined`. |
 | `create(meta): Promise<void>` | Register a new session's metadata. MAY defer the physical write until the first `append` (lazy materialization). |
 | `append(id, events): Promise<void>` | Durably persist a batch. Append-only; first event `seq` == stored next-seq after any repair; rejects non-JSON-serializable data naming the offending type. |
-| `load(id): Promise<{ meta; events }>` | Return a stored header plus a balanced contiguous log whose events are detached and validated and whose identified messages are deeply frozen. A live load first flushes its snapshot and rejects while its turn is open; a cold load preserves an interrupted final turn and closes it with synthetic `tool/result`/`step/end?`/`turn/end {interrupted}` events. Only a torn tail fragment is dropped; committed corruption, malformed messages, and unknown `version` reject. |
-| `inspect(id, signal?): Promise<{ meta; events }>` | Return a detached valid stored prefix with validated, deeply frozen identified messages, without truncating a torn tail, synthesizing recovery closers, or publishing coordinator state. Serialized with same-id writes; the optional signal promptly rejects a queued caller, prevents that queued backend read from starting, and cancels active backend read work. Intended for read models and other observers that must never recover a log. |
+| `load(id): Promise<{ meta; events }>` | Return a stored header plus a balanced contiguous log whose events are detached and validated and whose identified messages are deeply frozen. The coordinator upgrades the four pre-identity message event shapes into current wrappers in the returned snapshot; all other obsolete or malformed shapes still reject. A live load first flushes its snapshot and rejects while its turn is open; a cold load preserves an interrupted final turn and closes it with synthetic `tool/result`/`step/end?`/`turn/end {interrupted}` events. Only a torn tail fragment is dropped; committed corruption and unknown `version` reject. |
+| `inspect(id, signal?): Promise<{ meta; events }>` | Return a detached valid stored prefix with upgraded, validated, deeply frozen identified messages, without truncating a torn tail, synthesizing recovery closers, or publishing coordinator state. Serialized with same-id writes; the optional signal promptly rejects a queued caller, prevents that queued backend read from starting, and cancels active backend read work. Intended for read models and other observers that must never recover a log. |
+| `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | The read-from-seq primitive: return the header plus the valid stored events with `seq >= fromSeq`, detached and non-mutating like `inspect` (no truncation, no closers, no coordinator state). A `fromSeq` at or past the stored end returns an empty event list; a negative or non-safe-integer `fromSeq` rejects. Seek-capable backends (SQLite) read only the suffix; sequential backends (JSONL) still parse the whole artifact and skip forward — the primitive bounds what is returned and refolded, not every backend's physical read. Intended for checkpoint consumers (e.g. the persisted projection cache) that fold only the tail past a watermark. |
 | `list(signal?): Promise<SessionHeader[]>` | Lightweight listing from metadata, no full-log parse. The optional signal cancels backend listing work. A zero-event lazily-materialized session is absent from `list`. |
 | `listSnapshots(signal?): Promise<SessionPersistenceSnapshot[]>` | Lightweight metadata plus an opaque branded per-log revision, without loading event logs. A revision stays equal while that log and its backing store are unchanged, changes after append or mutating load repair, and cannot collide solely because two stores use the same local counter. The optional signal requests cancellation of backend discovery work; first-party backends settle any started listing work before rejecting so an awaited call is quiescent. |
 
@@ -33,6 +34,8 @@ Each `session/event` copies its event into the session controller and starts an
 
 Crash repair is cold-only. For a live id, `load(id)` snapshots the authoritative in-memory log, waits for that snapshot to become durable, and returns it with the coordinator's stored header only when balanced; an open live turn rejects instead of receiving synthetic interruption closers. A cold load reserves its id across backend reads and repair writes, so concurrent publication of a same-id live `Session` rejects and rolls back. HMR adoption reads through `loadStored`, applies the coordinator's cwd check, and never closes the active turn.
 
+Backend reads normalize pre-identity `user/message`, `assistant/message`, `tool/result`, and `steering/message` payloads before current-shape validation. Each imported message receives the deterministic id `legacy-message:<session-id>:<event-seq>`; a tool-result content replacement inherits its target's imported id. The coordinator uses the same normalized view for `load`, `inspect`, ownerless-state claims, and HMR prefix adoption, so resumed sessions can append current events without a false prefix collision. Storage remains append-only: the read does not rewrite old records, and every later append uses the current shape. This is the narrow import exception from the [pre-identity message recovery decision](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md), not a general v0 migration promise.
+
 When a live session emits `session/disposed`, the coordinator waits for its controller, serializes a final drain, then releases state owned by that exact `Session` object. Failed retirement leaves the controller in the live-session map, so backend teardown can retry it. Backend teardown stops event admission first, flushes every remaining controller, awaits per-id operations, and only then closes the storage handle.
 
 The side-effect-free `locate` and lightweight `listSnapshots` queries remain backend-owned because they describe storage topology and revision identity rather than write orchestration. `listSnapshots(signal?)` passes the caller's exact signal into backend discovery so observers can cancel that work without detaching it.
@@ -43,6 +46,7 @@ The `PersistenceBackend<TornMarker>` hooks (the only seam between the coordinato
 |---|---|
 | `name` | Backend label for the dispose-failure `AggregateError`. |
 | `loadStored(id, signal?)` | Read a stored prefix by id across every storage scope. Used by resume/load, non-mutating inspect, live adoption, and the create-collision probe. The optional signal belongs to observation-only reads. Returned metadata identifies `id`; an opaque `tornMarker` is present iff a torn tail must be truncated. |
+| `loadStoredFrom?(id, fromSeq, signal?)` | Optional seek-capable suffix read behind the service's `readFrom`: the header plus stored events with `seq >= fromSeq`, non-mutating, no torn marker. SQLite implements it (`WHERE seq >= ?`); a backend that omits it gets the coordinator's fallback — `loadStored` plus a forward skip. |
 | `appendBatch(meta, events, isMaterialized)` | Durably append a contiguous batch, lazily materializing ATOMICALLY when not yet materialized. |
 | `commitRepair(meta, tornMarker, closers)` | Make a crash repair durable: truncate the torn tail (iff `tornMarker !== undefined` — a marker may be falsy, e.g. seq/offset `0`) and append `closers`. NOT required to be atomic. Used by load (truncate + closers) and live-adoption (truncate only). |
 | `list(signal?)` | List all stored metadata, observing optional cancellation. |

packages/session-persistence/session-persistence/README.zh.md

@@ -13,8 +13,9 @@
 | `locate(meta): SessionLocation \| undefined` | 在不执行 I/O 或实体化的情况下解析绝对的每会话产物目标。没有独立本地产物的后端返回 `undefined`。 |
 | `create(meta): Promise<void>` | 注册新会话元数据。可以将物理写入延迟到第一次 `append`（延迟实体化）。 |
 | `append(id, events): Promise<void>` | 持久保存一个批次。仅追加；任何修复后，第一个事件 `seq` == 已存储 next-seq；非 JSON 可序列化数据会被拒绝，并命名违规类型。 |
-| `load(id): Promise<{ meta; events }>` | 返回已存储 header 和平衡、连续的日志，其中事件已脱离并验证，带标识的消息已深度冻结。实时 load 先 flush 其快照，并在轮次开放时拒绝；冷 load 保留中断的最终轮次，并用合成 `tool/result`/`step/end?`/`turn/end {interrupted}` 事件关闭它。只丢弃撕裂尾部碎片；已提交损坏、格式错误的消息和未知 `version` 会被拒绝。 |
-| `inspect(id, signal?): Promise<{ meta; events }>` | 返回脱离的有效已存储前缀，其中带标识的消息已经验证并深度冻结；不截断撕裂尾部、合成恢复 closer 或发布协调器状态。它与同 id 写入串行化；可选信号会迅速拒绝已排队调用方，阻止该后端读取启动，并取消活动后端读取工作。用于绝不应恢复日志的读模型和其他观察者。 |
+| `load(id): Promise<{ meta; events }>` | 返回已存储 header 和平衡、连续的日志，其中事件已脱离并验证，带标识的消息已深度冻结。协调器会在返回快照中，将消息标识机制引入前的四种消息事件形状升级为当前包装层；其余过时或格式错误的形状仍会被拒绝。实时 load 先 flush 其快照，并在轮次开放时拒绝；冷 load 保留中断的最终轮次，并用合成 `tool/result`/`step/end?`/`turn/end {interrupted}` 事件关闭它。只丢弃撕裂尾部碎片；已提交损坏和未知 `version` 会被拒绝。 |
+| `inspect(id, signal?): Promise<{ meta; events }>` | 返回脱离的有效已存储前缀，其中带标识的消息已经升级、验证并深度冻结；不截断撕裂尾部、合成恢复 closer 或发布协调器状态。它与同 id 写入串行化；可选信号会迅速拒绝已排队调用方，阻止该后端读取启动，并取消活动后端读取工作。用于绝不应恢复日志的读模型和其他观察者。 |
+| `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | read-from-seq 原语：返回 header 和 `seq >= fromSeq` 的有效已存储事件，与 `inspect` 同样脱离且非变更（不截断、不合成 closer、不发布协调器状态）。`fromSeq` 达到或超过已存储末尾时返回空事件列表；负数或非安全整数 `fromSeq` 会被拒绝。可寻址后端（SQLite）只读后缀；顺序后端（JSONL）仍解析整个产物并向前跳过——原语约束的是返回和重折叠的量，不是每个后端的物理读取。用于从水位续折尾部的 checkpoint 消费者（例如持久投影缓存）。 |
 | `list(signal?): Promise<SessionHeader[]>` | 从元数据轻量列出，不解析完整日志。可选信号取消后端列表工作。零事件延迟实体化会话不在 `list` 中。 |
 | `listSnapshots(signal?): Promise<SessionPersistenceSnapshot[]>` | 返回轻量元数据和不透明品牌化每日志修订，不加载事件日志。日志及其后端存储不变时，修订保持相等；append 或变更性 load 修复后会改变；不会仅因两个存储使用相同本地计数器而冲突。可选信号请求取消后端发现工作；第一方后端在拒绝前结算已启动列表工作，使已等待调用完全停稳。 |
 
@@ -33,6 +34,8 @@
 
 崩溃修复只适用于冷状态。对于实时 id，`load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时将其与协调器已存储 header 一起返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。冷 load 在后端读取和修复写入期间保留 id，因此同 id 实时 `Session` 的并发发布会拒绝并回滚。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
 
+后端读取会在当前形状验证前，规范化消息标识机制引入前的 `user/message`、`assistant/message`、`tool/result` 以及 steering（中途引导）对应的 `steering/message` 载荷。每条导入消息都会获得确定性的 id `legacy-message:<session-id>:<event-seq>`；工具结果的内容替换会继承其目标导入后的 id。协调器对 `load`、`inspect`、无 owner 状态的认领和 HMR 前缀接管使用同一份规范化视图，因此恢复后的会话可以追加当前事件，不会被误判为发生前缀冲突。存储仍然仅追加：读取不会重写旧记录，此后追加的每个事件都使用当前形状。这是[消息标识机制引入前的消息恢复决策](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
+
 实时会话发出 `session/disposed` 时，协调器等待其 controller，串行化最终 drain，然后释放该精确 `Session` 对象拥有的状态。失败退役会将 controller 保留在实时会话 map 中，使后端拆卸可重试。后端拆卸先停止事件接纳，flush 每个剩余 controller，等待每 id 操作，最后才关闭存储句柄。
 
 无副作用 `locate` 和轻量 `listSnapshots` 查询仍由后端负责，因为它们描述存储拓扑和修订身份，而非写入编排。`listSnapshots(signal?)` 将调用方的精确信号传入后端发现，使观察者可在不脱离该工作的情况下取消。
@@ -43,6 +46,7 @@
 |---|---|
 | `name` | dispose 失败 `AggregateError` 的后端标签。 |
 | `loadStored(id, signal?)` | 在全部存储范围中按 id 读取已存储前缀。用于 resume/load、非变更 inspect、实时接管和 create 冲突探测。可选信号属于仅观察读取。返回元数据标识 `id`；当且仅当必须截断撕裂尾部时才存在不透明 `tornMarker`。 |
+| `loadStoredFrom?(id, fromSeq, signal?)` | 服务 `readFrom` 背后的可选可寻址后缀读取：返回 header 和 `seq >= fromSeq` 的已存储事件，非变更、无撕裂标记。SQLite 实现它（`WHERE seq >= ?`）；不实现的后端使用协调器回退——`loadStored` 加向前跳过。 |
 | `appendBatch(meta, events, isMaterialized)` | 持久追加连续批次；尚未实体化时以原子方式延迟实体化。 |
 | `commitRepair(meta, tornMarker, closers)` | 使崩溃修复持久：截断撕裂尾部（当且仅当 `tornMarker !== undefined`；标记可为 falsy，例如 seq/offset `0`），并追加 `closers`。不要求原子性。由 load（截断 + closer）和实时接管（仅截断）使用。 |
 | `list(signal?)` | 列出全部已存储元数据，观察可选取消。 |

packages/session-persistence/session-persistence/src/coordinator.ts

@@ -25,6 +25,17 @@ export interface StoredPrefix<TornMarker = unknown> {
   tornMarker?: TornMarker
 }
 
+/**
+ * A stored session's header plus the events at or past a requested seq — the
+ * return shape of the optional seek-capable
+ * {@link PersistenceBackend.loadStoredFrom} hook. Non-mutating reads carry no
+ * torn marker: there is nothing to repair.
+ */
+export interface StoredSuffix {
+  meta: SessionHeader
+  events: SessionEvent[]
+}
+
 /**
  * The storage seam between {@link PersistenceCoordinator} and a concrete
  * backend: the minimal set of durable primitives the orchestration calls. A
@@ -50,6 +61,22 @@ export interface PersistenceBackend<TornMarker = unknown> {
    */
   loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<TornMarker> | undefined>
 
+  /**
+   * Optional seek-capable suffix read behind the service's `readFrom`: return
+   * the header plus the stored events with `seq >= fromSeq` without reading
+   * the whole log. A backend whose medium can address events by seq (SQLite)
+   * implements this so `readFrom` scales with the suffix; sequential backends
+   * omit it and the coordinator falls back to {@link loadStored} plus a
+   * forward skip. Non-mutating (no truncation, no closers). Validation of the
+   * region strictly below `fromSeq` is limited to seq contiguity — the
+   * service contract scopes this read to the suffix.
+   * @param id - persisted session id to resolve.
+   * @param fromSeq - first event seq to include (non-negative safe integer,
+   *   validated by the coordinator before this hook runs).
+   * @param signal - optional cancellation for backend read work.
+   */
+  loadStoredFrom?(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined>
+
   /**
    * Durably append a CONTIGUOUS batch, lazily materializing the session first
    * when `!isMaterialized`. The materialize-write and the first event batch MUST
@@ -146,10 +173,142 @@ function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId):
   }
 }
 
-/** Materialize stored events as validated snapshots with immutable messages. */
+/** Return an object record without widening arrays into message payloads. */
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+type PersistedMessageId = SessionEvent<'user/message'>['data']['id']
+
+/** Mint the stable import identity for a message persisted before identities existed. */
+function legacyMessageId(id: SessionId, seq: number): PersistedMessageId {
+  return `legacy-message:${id}:${seq}` as PersistedMessageId
+}
+
+/** Read a replacement target while leaving malformed surface metadata to the session validator. */
+function replacementStart(event: SessionEvent): number | undefined {
+  const op = asRecord((event as SessionEvent & { surfaceOp?: unknown }).surfaceOp)
+  return op?.['op'] === 'replace' && typeof op['start'] === 'number'
+    ? op['start']
+    : undefined
+}
+
+/**
+ * Upgrade one pre-identity message event into the current wrapper shape.
+ * Current-looking malformed events remain untouched so validation rejects them
+ * instead of disguising corruption as legacy data.
+ */
+function migrateLegacyMessageEvent(
+  event: SessionEvent,
+  id: SessionId,
+  messageIds: ReadonlyMap<number, PersistedMessageId>,
+): SessionEvent {
+  const data = asRecord(event.data)
+  if (data === undefined) return event
+  switch (event.type) {
+    case 'user/message': {
+      if (Object.hasOwn(data, 'id') || Object.hasOwn(data, 'role')
+        || Object.hasOwn(data, 'message')
+        || !Object.hasOwn(data, 'content') || !Object.hasOwn(data, 'source')) return event
+      return {
+        ...event,
+        data: {
+          ...data,
+          id: legacyMessageId(id, event.seq),
+          role: 'user',
+        },
+      } as SessionEvent
+    }
+    case 'assistant/message': {
+      if (Object.hasOwn(data, 'message')
+        || !Object.hasOwn(data, 'content') || !Object.hasOwn(data, 'provenance')) return event
+      const { content, provenance, ...eventData } = data
+      return {
+        ...event,
+        data: {
+          ...eventData,
+          message: {
+            id: legacyMessageId(id, event.seq),
+            role: 'assistant',
+            content,
+            source: {
+              ...asRecord(provenance),
+              kind: 'model',
+            },
+          },
+        },
+      } as SessionEvent
+    }
+    case 'tool/result': {
+      if (Object.hasOwn(data, 'message')
+        || !Object.hasOwn(data, 'callId') || !Object.hasOwn(data, 'content')
+        || !Object.hasOwn(data, 'isError')) return event
+      const { callId, content, isError, ...eventData } = data
+      const inheritedId = replacementStart(event)
+      return {
+        ...event,
+        data: {
+          ...eventData,
+          message: {
+            id: inheritedId === undefined
+              ? legacyMessageId(id, event.seq)
+              : messageIds.get(inheritedId),
+            role: 'user',
+            content: [{
+              type: 'tool-result',
+              toolCallId: callId,
+              content,
+              isError,
+            }],
+            source: {
+              kind: 'tool',
+              callId,
+            },
+          },
+        },
+      } as SessionEvent
+    }
+    case 'steering/message': {
+      if (Object.hasOwn(data, 'message')
+        || !Object.hasOwn(data, 'content') || !Object.hasOwn(data, 'source')) return event
+      const { content, source, ...eventData } = data
+      return {
+        ...event,
+        data: {
+          ...eventData,
+          message: {
+            id: legacyMessageId(id, event.seq),
+            role: 'user',
+            content,
+            source,
+          },
+        },
+      } as SessionEvent
+    }
+    default:
+      return event
+  }
+}
+
+/** Read the identified message carried by one validated current event. */
+function eventMessageId(event: SessionEvent): PersistedMessageId | undefined {
+  const data = asRecord(event.data)
+  const message = event.type === 'user/message' ? data : asRecord(data?.['message'])
+  return typeof message?.['id'] === 'string' ? message['id'] as PersistedMessageId : undefined
+}
+
+/** Materialize stored events as upgraded, validated snapshots with immutable messages. */
 function snapshotStoredEvents(events: readonly SessionEvent[], id: SessionId): SessionEvent[] {
   assertSupportedEvents(events, id)
-  return events.map(snapshotSessionEvent)
+  const messageIds = new Map<number, PersistedMessageId>()
+  return events.map((event) => {
+    const snapshot = snapshotSessionEvent(migrateLegacyMessageEvent(event, id, messageIds))
+    const messageId = eventMessageId(snapshot)
+    if (messageId !== undefined) messageIds.set(snapshot.seq, messageId)
+    return snapshot
+  })
 }
 
 /**
@@ -325,6 +484,52 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     }
   }
 
+  /**
+   * Read the stored events from `fromSeq` onward, detached and non-mutating
+   * (the read-from-seq primitive behind the service's `readFrom`). Runs on
+   * the same per-id chain as writes; a backend with the seek-capable
+   * {@link PersistenceBackend.loadStoredFrom} hook reads only the suffix,
+   * every other backend reads its stored prefix and skips forward here.
+   * @param id - persisted session to read.
+   * @param fromSeq - first event seq to include; a non-negative safe integer.
+   * @param signal - optional cancellation for queued and backend read work.
+   * @returns stored header and the valid stored events with `seq >= fromSeq`.
+   */
+  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    if (!Number.isSafeInteger(fromSeq) || fromSeq < 0) {
+      return Promise.reject(new TypeError(`readFrom fromSeq must be a non-negative safe integer, got ${String(fromSeq)}`))
+    }
+    const retired = Promise.resolve(this.retirements.get(id))
+    const waited = signal === undefined ? retired : observeQueuedAbort(retired, signal, () => false)
+    return waited.then(() => this.serialize(id, () => this.readFromCore(id, fromSeq, signal), signal))
+  }
+
+  private async readFromCore(
+    id: SessionId,
+    fromSeq: number,
+    signal?: AbortSignal,
+  ): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    signal?.throwIfAborted()
+    if (this.backend.loadStoredFrom !== undefined) {
+      let suffix: StoredSuffix | undefined
+      try {
+        suffix = await this.backend.loadStoredFrom(id, fromSeq, signal)
+      } catch (error: unknown) {
+        if (signal?.aborted) signal.throwIfAborted()
+        throw error
+      }
+      signal?.throwIfAborted()
+      if (suffix === undefined) throw new Error(`session "${id}" not found`)
+      this.assertStoredId(id, suffix.meta)
+      this.assertVersion(suffix.meta)
+      assertSupportedEvents(suffix.events, id)
+      return { meta: structuredClone(suffix.meta), events: structuredClone(suffix.events) }
+    }
+    const whole = await this.inspectCore(id, signal)
+    // Sequential fallback: contiguous seqs from 0 make the suffix an index slice.
+    return { meta: whole.meta, events: whole.events.slice(fromSeq) }
+  }
+
   private async loadCore(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     const stored = await this.backend.loadStored(id)
     if (stored === undefined) throw new Error(`session "${id}" not found`)
@@ -526,7 +731,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     /* v8 ignore next -- a cursor > 0 means the session was materialized, so it exists */
     if (stored === undefined) return false
     this.assertStoredId(id, stored.meta)
-    return seedCoversPrefix(seed, stored.events.slice(0, cursor))
+    return seedCoversPrefix(seed, snapshotStoredEvents(stored.events, id).slice(0, cursor))
   }
 
   /**
@@ -614,19 +819,19 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       throw new Error(`session "${session.header.id}" is already persisted at a different cwd (persisted: ${String(meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
     }
     this.assertVersion(meta)
-    assertSupportedEvents(events, session.header.id)
-    if (!seedCoversPrefix(seed, events)) {
+    const storedEvents = snapshotStoredEvents(events, session.header.id)
+    if (!seedCoversPrefix(seed, storedEvents)) {
       throw new Error(`session "${session.header.id}" already has a persisted log on disk that does not match this live session (id collision)`)
     }
     // Truncate-only repair (no closers): the open turn is NOT closed here.
     if (tornMarker !== undefined) await this.backend.commitRepair(meta, tornMarker, [])
     this.states.set(session.header.id, {
       meta: { ...meta },
-      cursor: events.length,
+      cursor: storedEvents.length,
       materialized: true,
       owner: session,
     })
-    const suffix = seed.slice(events.length)
+    const suffix = seed.slice(storedEvents.length)
     if (suffix.length > 0) await this.appendCore(session.header.id, suffix)
   }
 

packages/session-persistence/session-persistence/src/index.ts

@@ -23,7 +23,7 @@ export interface SessionPersistenceSnapshot {
 
 // The backend-agnostic write-path orchestration first-party backends compose.
 export { PersistenceCoordinator } from './coordinator.ts'
-export type { PersistenceBackend, StoredPrefix } from './coordinator.ts'
+export type { PersistenceBackend, StoredPrefix, StoredSuffix } from './coordinator.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -93,7 +93,9 @@ export abstract class SessionPersistence extends Service {
    * A coordinator-backed cold load reserves the identity across storage awaits,
    * so concurrent publication of a same-id live Session rejects.
    * Returned events are detached, and every identified message is deeply
-   * frozen; malformed identified messages reject before any stored event is returned.
+   * frozen. Coordinator-backed implementations upgrade supported pre-identity
+   * message events before validation; other malformed messages reject before
+   * any stored event is returned.
    * @param id - the persisted session to reload.
    * @returns the header and a log ending on a balanced `turn/end`.
    */
@@ -103,14 +105,35 @@ export abstract class SessionPersistence extends Service {
    * Inspect a header and its valid contiguous stored prefix without repairing
    * a torn tail, closing an interrupted turn, or publishing coordinator state.
    * This read is serialized with writes for the same id and returns detached
-   * values with deeply frozen identified messages, so observers cannot mutate message
-   * identity/content or backend-owned state. Malformed identified messages reject.
+   * values with upgraded, deeply frozen identified messages, so observers
+   * cannot mutate message identity/content or backend-owned state. Other
+   * malformed messages reject.
    * @param id - the persisted session to inspect.
    * @param signal - optional cancellation for queued and backend read work.
    * @returns the header and valid stored event prefix exactly as observed.
    */
   abstract inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
 
+  /**
+   * Read the stored events from `fromSeq` onward — the read-from-seq
+   * primitive for read models that resume from a watermark (e.g. a persisted
+   * projection cache folding only the tail past its checkpoint). Like
+   * {@link inspect} it is non-mutating and detached: no torn-tail truncation,
+   * no synthetic closers, no coordinator-state publication; only events from
+   * the valid contiguous stored prefix are returned, so a torn fragment never
+   * reaches the caller. `fromSeq` at or beyond the stored prefix returns an
+   * empty event list (never an error). Backends whose medium can seek by seq
+   * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
+   * still parse the whole artifact and skip forward — the primitive bounds
+   * what is RETURNED and refolded, not every backend's physical read.
+   * @param id - the persisted session to read.
+   * @param fromSeq - first event seq to include; a non-negative safe integer.
+   * @param signal - optional cancellation for queued and backend read work.
+   * @returns the header and the stored events with `seq >= fromSeq`.
+   */
+  abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal):
+  Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
   /**
    * Lightweight listing from metadata, without a full-log parse.
    * @param signal - optional cancellation for backend listing work.

packages/session-persistence/session-persistence/tests/contract.ts

@@ -289,6 +289,43 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
         await expect(persistence.listSnapshots(controller.signal)).rejects.toBe(reason)
         await expect(persistence.inspect(SessionId('cancelled-inspect'), controller.signal))
           .rejects.toBe(reason)
+        await expect(persistence.readFrom(SessionId('cancelled-read-from'), 0, controller.signal))
+          .rejects.toBe(reason)
+      } finally {
+        await dispose()
+      }
+    })
+
+    it('readFrom returns exactly the stored suffix from the requested seq, without mutating the log', async () => {
+      const { persistence, dispose } = await make()
+      try {
+        const m = meta('read-from', '/work')
+        const log = oneTurnLog()
+        await persistence.create(m)
+        await persistence.append(m.id, log)
+
+        const whole = await persistence.readFrom(m.id, 0)
+        expect(whole.meta).toMatchObject({ id: m.id, cwd: '/work' })
+        expect(whole.events).toEqual(log)
+
+        const suffix = await persistence.readFrom(m.id, 3)
+        expect(suffix.events).toEqual(log.slice(3))
+        expect(suffix.events[0]?.seq).toBe(3)
+
+        // At/past the stored end: an empty tail, never an error.
+        await expect(persistence.readFrom(m.id, log.length)).resolves.toMatchObject({ events: [] })
+        await expect(persistence.readFrom(m.id, log.length + 100)).resolves.toMatchObject({ events: [] })
+
+        // Non-mutating: an interrupted-turn log is served as stored, no closers.
+        await persistence.append(m.id, [
+          { type: 'turn/start', seq: 6, time: 7, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
+        ])
+        const tail = await persistence.readFrom(m.id, 6)
+        expect(tail.events.map(event => event.type)).toEqual(['turn/start'])
+
+        await expect(persistence.readFrom(SessionId('absent-read-from'), 0)).rejects.toThrow('not found')
+        await expect(persistence.readFrom(m.id, -1)).rejects.toThrow('non-negative safe integer')
+        await expect(persistence.readFrom(m.id, 1.5)).rejects.toThrow('non-negative safe integer')
       } finally {
         await dispose()
       }

packages/session-persistence/session-persistence/tests/coordinator-contract.ts

@@ -13,8 +13,8 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { describe, expect, it, vi } from 'vitest'
 import { Context, type Fiber } from 'cordis'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
-import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { meta, oneTurnLog, appendLog } from './contract.ts'
 
 /**
@@ -45,6 +45,80 @@ function send(session: Session, events: readonly SessionEvent[]): void {
   appendLog(session, events)
 }
 
+/** A valid persisted log from immediately before messages gained wrappers and identities. */
+function legacyMessageLog(): SessionEvent[] {
+  return [
+    { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    {
+      type: 'user/message',
+      seq: 1,
+      time: 2,
+      data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } },
+      surfaceOp: 'append',
+    },
+    { type: 'step/start', seq: 2, time: 3, data: { turn: 1, step: 1 } },
+    {
+      type: 'assistant/message',
+      seq: 3,
+      time: 4,
+      data: {
+        turn: 1,
+        step: 1,
+        content: [{ type: 'tool-call', id: 'call-1', name: 'read', arguments: '{}' }],
+        provenance: { provider: 'mock', model: 'mock' },
+      },
+      surfaceOp: 'append',
+    },
+    {
+      type: 'tool/call',
+      seq: 4,
+      time: 5,
+      data: { turn: 1, step: 1, callId: 'call-1', name: 'read', arguments: '{}' },
+    },
+    {
+      type: 'tool/result',
+      seq: 5,
+      time: 6,
+      data: {
+        turn: 1,
+        step: 1,
+        callId: 'call-1',
+        content: [{ type: 'text', text: 'full result' }],
+        isError: false,
+      },
+      sourceEventSeqs: [4],
+      surfaceOp: 'append',
+    },
+    {
+      type: 'steering/message',
+      seq: 6,
+      time: 7,
+      data: {
+        turn: 1,
+        content: [{ type: 'text', text: 'continue' }],
+        source: { kind: 'plugin', plugin: 'test' },
+      },
+      surfaceOp: 'append',
+    },
+    {
+      type: 'tool/result',
+      seq: 7,
+      time: 8,
+      data: {
+        turn: 1,
+        step: 1,
+        callId: 'call-1',
+        content: [{ type: 'text', text: 'pruned' }],
+        isError: false,
+      },
+      sourceEventSeqs: [5],
+      surfaceOp: { op: 'replace', start: 5, end: 5 },
+    },
+    { type: 'step/end', seq: 8, time: 9, data: { turn: 1, step: 1 } },
+    { type: 'turn/end', seq: 9, time: 10, data: { turn: 1, reason: { kind: 'completed' } } },
+  ] as unknown as SessionEvent[]
+}
+
 /** A live session created inside its OWN fiber, so it survives a backend reload. */
 async function liveSessionInFiber(
   ctx: Context, id: string, cwd: string | undefined,
@@ -269,6 +343,48 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
+    it('loads pre-identity message logs into resumable current sessions', async () => {
+      const fix = await makeFixture()
+      const { ctx, fiber } = await freshCtx(fix)
+      try {
+        const id = SessionId('legacy-message-load')
+        await ctx.sessionPersistence.create(meta(id, WORK))
+        await ctx.sessionPersistence.append(id, legacyMessageLog())
+
+        for (const snapshot of [
+          await ctx.sessionPersistence.inspect(id),
+          await ctx.sessionPersistence.load(id),
+        ]) {
+          const messages = snapshot.events.flatMap((event) => {
+            if (event.type === 'user/message') return [event.data]
+            if (event.type === 'assistant/message'
+              || event.type === 'tool/result'
+              || event.type === 'steering/message') return [event.data.message]
+            return []
+          })
+          expect(messages.map(message => message.id)).toEqual([
+            `legacy-message:${id}:1`,
+            `legacy-message:${id}:3`,
+            `legacy-message:${id}:5`,
+            `legacy-message:${id}:6`,
+            `legacy-message:${id}:5`,
+          ])
+          expect(messages.every(message => Object.isFrozen(message))).toBe(true)
+
+          const resumed = new Session(id, snapshot.events, snapshot.meta)
+          expect(resumed.deriveMessages().map(message => message.id)).toEqual([
+            `legacy-message:${id}:1`,
+            `legacy-message:${id}:3`,
+            `legacy-message:${id}:5`,
+            `legacy-message:${id}:6`,
+          ])
+        }
+      } finally {
+        await fiber.dispose()
+        await fix.cleanup()
+      }
+    })
+
     it('rejects malformed persisted message events before returning them', async () => {
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
@@ -292,6 +408,31 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
           .rejects.toThrow('message must have role "user"')
         await expect(ctx.sessionPersistence.load(id))
           .rejects.toThrow('message must have role "user"')
+
+        for (const type of ['tool/result', 'steering/message'] as const) {
+          const malformedId = SessionId(`invalid-${type}`)
+          await ctx.sessionPersistence.create(meta(malformedId, WORK))
+          await ctx.sessionPersistence.append(malformedId, [{
+            type,
+            seq: 0,
+            time: 1,
+            surfaceOp: 'append',
+            data: { message: null },
+          } as unknown as SessionEvent])
+          await expect(ctx.sessionPersistence.inspect(malformedId))
+            .rejects.toThrow('lacks an identified message')
+        }
+
+        const pluginId = SessionId('non-object-plugin-event')
+        await ctx.sessionPersistence.create(meta(pluginId, WORK))
+        await ctx.sessionPersistence.append(pluginId, [{
+          type: 'plugin/test',
+          seq: 0,
+          time: 1,
+          data: null,
+        } as unknown as SessionEvent])
+        await expect(ctx.sessionPersistence.inspect(pluginId))
+          .resolves.toMatchObject({ events: [{ type: 'plugin/test', data: null }] })
       } finally {
         await fiber.dispose()
         await fix.cleanup()

packages/session-persistence/session-persistence/tests/persistence.spec.ts

@@ -99,6 +99,10 @@ class MemoryPersistence extends SessionPersistence implements PersistenceBackend
     return this.coordinator.inspect(id, signal)
   }
 
+  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.readFrom(id, fromSeq, signal)
+  }
+
   // --- PersistenceBackend hooks (the Map storage primitives) ---
 
   // A Map-backed store has no torn tails, so `tornMarker` is never set.
@@ -157,6 +161,13 @@ class ControlledBackend implements PersistenceBackend<never> {
   repairAttempts = 0
   beforeAppend?: (attempt: number) => Promise<void>
   beforeLoadStored?: (attempt: number, signal?: AbortSignal) => Promise<void>
+  /** When set, the declared seek hook delegates here so readFrom exercises it; unset throws (tests set it first). */
+  seekHook?: (id: SessionId, fromSeq: number, signal?: AbortSignal) => Promise<StoredPrefix<never> | undefined>
+
+  loadStoredFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredPrefix<never> | undefined> {
+    if (this.seekHook === undefined) throw new Error('seekHook not configured for this test')
+    return this.seekHook(id, fromSeq, signal)
+  }
 
   async loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<never> | undefined> {
     await this.beforeLoadStored?.(++this.loadAttempts, signal)
@@ -453,6 +464,58 @@ describe('PersistenceCoordinator observation cancellation', () => {
     }
   })
 
+  it('readFrom via the seek hook: serves the suffix, maps undefined to not-found, and relays hook failures by abort state', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    const id = SessionId('seek-read-from')
+    const log = oneTurnLog()
+    backend.store.set(id, { meta: meta(id), events: log })
+    let coordinator!: PersistenceCoordinator<never>
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+
+    try {
+      // Happy path through the hook: only the suffix comes back, detached.
+      backend.seekHook = async (hookId, fromSeq) => {
+        const entry = backend.store.get(hookId)
+        if (entry === undefined) return undefined
+        return { meta: structuredClone(entry.meta), events: entry.events.filter(e => e.seq >= fromSeq) }
+      }
+      const suffix = await coordinator.readFrom(id, 3)
+      expect(suffix.events).toEqual(log.slice(3))
+      // The hook's undefined is the seam's not-found.
+      await expect(coordinator.readFrom(SessionId('missing-seek'), 0)).rejects.toThrow('not found')
+
+      // A hook failure with no cancellation in play propagates as-is.
+      const hookFailure = new Error('seek backend exploded')
+      backend.seekHook = () => Promise.reject(hookFailure)
+      await expect(coordinator.readFrom(id, 0)).rejects.toBe(hookFailure)
+
+      // A hook failure after cancellation surfaces the caller's abort reason,
+      // not the backend's internal teardown error. The abort fires only once
+      // the hook is provably entered, so the failure exercises the catch (not
+      // the pre-invocation throwIfAborted).
+      const controller = new AbortController()
+      const reason = new Error('read-from cancelled mid-hook')
+      let hookEntered = false
+      backend.seekHook = async (_hookId, _fromSeq, signal) => {
+        hookEntered = true
+        await new Promise<void>((resolve) => { signal?.addEventListener('abort', () => { resolve() }, { once: true }) })
+        throw new Error('backend teardown after abort')
+      }
+      const pending = coordinator.readFrom(id, 0, controller.signal)
+      const observed = pending.catch((error: unknown) => error)
+      await vi.waitFor(() => { expect(hookEntered).toBe(true) })
+      controller.abort(reason)
+      expect(await observed).toBe(reason)
+    } finally {
+      await fiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
   it('rejects a cancelled inspect while an in-flight retirement drain is still pending', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
@@ -537,6 +600,66 @@ describe('PersistenceCoordinator retirement', () => {
     }
   })
 
+  it('a superseded retirement leaves the successor lifecycle\'s pending drain in place', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const backend = new ControlledBackend()
+    let coordinator!: PersistenceCoordinator<never>
+    const backendFiber = await ctx.plugin(Object.assign((inner: Context) => {
+      coordinator = new PersistenceCoordinator(inner, backend)
+    }, { inject: ['sessions'] }))
+    const internals = coordinator as unknown as CoordinatorInternals
+    const readGate = Promise.withResolvers<boolean>()
+
+    try {
+      const id = SessionId('superseded-retirement')
+      // First lifecycle: unmaterialized (zero events), so a same-id successor
+      // may legally reclaim the abandoned id later.
+      let first!: Session
+      const firstFiber = await ctx.plugin(Object.assign((inner: Context) => {
+        first = inner.sessions.create(id)
+      }, { inject: ['sessions'] }))
+      await ctx.sessions.flush(first)
+
+      // Occupy the per-id serialize chain with a gated read: everything the
+      // two retirements queue stays pending behind it. (Attempt counting
+      // starts here — an absent beforeLoadStored short-circuits the optional
+      // call without evaluating its ++ argument.)
+      backend.beforeLoadStored = async (attempt) => {
+        if (attempt === 1) await readGate.promise
+      }
+      const parked = coordinator.inspect(id).catch((error: unknown) => error)
+      await vi.waitFor(() => { expect(backend.loadAttempts).toBe(1) })
+
+      // First retirement queues behind the gate and stays pending.
+      await firstFiber.dispose()
+      await vi.waitFor(() => { expect(internals.retirements.has(id)).toBe(true) })
+      const firstRetirement = internals.retirements.get(id)
+
+      // Successor lifecycle retires while the first drain is still in flight:
+      // retire() replaces the map entry synchronously.
+      const secondFiber = await ctx.plugin(Object.assign((inner: Context) => {
+        inner.sessions.create(id)
+      }, { inject: ['sessions'] }))
+      await secondFiber.dispose()
+      await vi.waitFor(() => {
+        expect(internals.retirements.get(id)).not.toBe(firstRetirement)
+      })
+
+      // Release the chain: the first drain settles and its forget() must not
+      // delete the successor's entry (exact-entry guard); the successor's own
+      // forget() then clears the map.
+      readGate.resolve(true)
+      expect(await parked).toBeInstanceOf(Error) // the parked inspect (not found) is observed
+      await firstRetirement
+      await vi.waitFor(() => { expect(internals.retirements.has(id)).toBe(false) })
+    } finally {
+      readGate.resolve(true)
+      await backendFiber.dispose()
+      await ctx.fiber.dispose()
+    }
+  })
+
   it('a replacement queued before retirement cleanup still collides with the live owner', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)

packages/session-projection/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session-projection/README.md
-README.md: 81c67d56e136ba4853e86d889b485d4df80ac1fe
-README.zh.md: 72e23b78a48a989f355f9be3d34d81a440ca1d04
+README.md: ae80a905705d205adb4a1ee66c72fa28d0d8b6d6
+README.zh.md: 97e25dd16caeeb444f5f5309eed3341d422fa1b1

packages/session-projection/README.md

@@ -7,3 +7,4 @@ Session-projection capability family: the seam through which domain host plugins
 | Package | ctx key | Role |
 |---|---|---|
 | [`session-projection`](session-projection/README.md) | `sessionProjections` | The interface package: the merge-extensible `SessionProjectionMap` type table, the `ProjectionDefinition` unit contract, and the eagerly driven registry carriers read synchronously |
+| [`session-projection-cache`](session-projection-cache/README.md) | `sessionProjectionCache` | Persisted projection cache: durable per-session unit checkpoints over the domain data form, throttled write-behind with mandatory turn/end + detach points, and the cold-read ladder (cache row + persistence tail replay) |

packages/session-projection/README.zh.md

@@ -7,3 +7,4 @@
 | 包 | ctx 键 | 职责 |
 |---|---|---|
 | [`session-projection`](session-projection/README.md) | `sessionProjections` | 接口包（package）：merge-extensible 的 `SessionProjectionMap` 类型表、`ProjectionDefinition` 单元契约，以及供载体同步读取的正向驱动注册表 |
+| [`session-projection-cache`](session-projection-cache/README.md) | `sessionProjectionCache` | 持久投影缓存：基于域数据形态的按会话单元 checkpoint 持久化、带 turn/end + detach 两个必写点的节流后写，以及冷读阶梯（缓存行 + 持久化尾部重放） |

packages/session-projection/session-projection-cache/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/session-projection/session-projection-cache/README.md
+README.md: 5d4ad07fab6648acdb40c6aa86d32cc78b4c016e
+README.zh.md: ab4076df28cfe2b5a8b41d609967039dcacb7ef4

packages/session-projection/session-projection-cache/README.md

@@ -0,0 +1,62 @@
+# @deepseek-ai/dsh-session-projection-cache
+
+English | [中文](README.zh.md)
+
+The persisted projection cache (`ctx.sessionProjectionCache`): durable checkpoints of every registered projection unit's state, one record per session on the domain data form (`session_projcache` domain — the shipped json backend lands it beside `workspace.json` under the configured storage root). Design authority: the [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) (persisted projection cache section).
+
+A stored row `(key → {ver, seq, val})` is a fold shortcut, never an authority: possibly stale (`seq` says exactly how stale) but never wrong. Consequences the implementation commits to:
+
+- **Every background write is fail-soft.** A failed durable write logs a warning and keeps the cache stale; the next write or cold read self-heals. A crash between writes costs a longer tail replay, never a wrong value.
+- **A `ver` mismatch against the live unit's `stateVersion` discards, never migrates.** A unit bump invalidates its rows at read time; the key refolds from the log.
+- **Whole-record writes.** Each write replaces the session's full checkpoint (the registry cut is always complete), snapshotted through the lossless-JSON boundary — a unit state violating the plain-JSON contract fails loud.
+- **Records are bound to a log lifecycle, not just an id.** Each record stores the header identity (`createdAt`, `cwd`) it was folded from; every read validates it (the live or stored header is the witness) before accepting a row, so a deleted-then-recreated id or a persistence store swapped under a surviving cache discards the unrelated record instead of seeding phantom values.
+- **The log leads, the cache follows.** A live checkpoint flushes the session's buffered events durably BEFORE the cache row lands, so a crash can leave the cache behind the log (a longer tail replay) but never ahead of it.
+
+## Write policy
+
+Two mandatory points, throttled in between:
+
+| Trigger | Nature |
+|---|---|
+| `turn/end` | Mandatory — the turn-final value is what cold reads want. |
+| Session disposal (detach) | Mandatory — the live-to-cold moment; after it the cold ladder serves this session. |
+| `writeEveryEvents` committed events | Config throttle (count). |
+| `writeIntervalMs` since the first dirty event | Config throttle (interval). |
+
+Both `Config` fields are required (no defaults): flush cadence is a deployment choice with no universally correct value, stated in cordis.yml.
+
+## Listing read (`cachedSnapshot(meta)`)
+
+The zero-I/O rung: whole values viewed straight from the identity-matching stored record (version-matching keys only), returned as a `{asOfSeq, values}` cut — `asOfSeq` is the lowest served-row watermark, so a client seeding its per-session value store under higher-seq-wins can never let a stale list block overwrite a newer push frame. `undefined` when no usable record exists (unknown id, unrelated lifecycle, or no version-matching rows); the api-proxy list carrier turns that into an absent column.
+
+## Cold read (`coldSnapshot(id, signal?)`)
+
+The read ladder, zero full-log load on the happy path: cached rows → `sessionProjections.restoreFloor` (anchored one event below the lowest usable watermark) → persistence `readFrom(id, floor)` → `sessionProjections.restore` → fail-soft write-back of the refreshed rows. The anchor makes a shrunk log (crash-repair truncation) provable: an overreaching row triggers exactly one full re-read from seq 0 instead of serving a ghost value. No registered units serve `{asOfSeq: -1, values: {}}` without touching persistence; a session with no persisted log rejects with the seam's `not found`.
+
+`write(session)` is the synchronous-cut checkpoint both mandatory points use; carriers may call it directly (not fail-soft — the fail-soft wrappers own containment).
+
+## Composition
+
+```yaml
+- id: session-projection-cache
+  name: '@deepseek-ai/dsh-session-projection-cache'
+  config:
+    writeEveryEvents: 200
+    writeIntervalMs: 5000
+```
+
+Injects `storageDomain`, `sessionProjections`, `sessionPersistence`, `sessions`. Without this row the projection system runs live-only (watermark cache; cold reads fall back to full log loads wherever a carrier implements them).
+
+## Model Experience
+
+None, as the cache only persists and restores host-side read models of already-logged session state and touches no prompt, message, schema, stream, or tool result.
+
+#### KV Cache effect
+
+None; the cache never assembles or sends provider requests.
+
+## Known Limitations and Deferred Work
+
+- **No eviction or retention surface** — records accumulate per session; pruning stored checkpoints is out-of-band maintenance, same stance as session persistence itself.
+- **Interval throttle is per-session coarse** — the timer arms at the first dirty event after a clean write; a steady sub-threshold trickle writes once per interval, not a sliding window.
+- **`coldSnapshot` reads are not deduplicated** — two concurrent cold reads of one session each run the ladder; last write-back wins (rows are equivalent), acceptable for listing-scale call rates.

packages/session-projection/session-projection-cache/README.zh.md

@@ -0,0 +1,62 @@
+# @deepseek-ai/dsh-session-projection-cache
+
+[English](README.md) | 中文
+
+持久投影缓存（`ctx.sessionProjectionCache`）：把每个已注册投影单元的状态持久化为检查点（checkpoint），基于域数据形态（domain data form）每会话一条记录（`session_projcache` 域——出厂 json 后端将其落在配置的存储根目录下、`workspace.json` 旁边）。设计权威：[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md)（persisted projection cache 一节）。
+
+一条存储行 `(key → {ver, seq, val})` 是折叠捷径，绝不是权威：可能陈旧（`seq` 精确说明陈旧到哪），但绝不会错。实现据此承诺：
+
+- **每次后台写入都 fail-soft。** 持久写失败只记一条警告并保持缓存陈旧；下一次写入或冷读自愈。两次写之间崩溃的代价是更长的尾部重放，绝不是错误的值。
+- **`ver` 与活单元 `stateVersion` 不匹配即丢弃，绝不迁移。** 单元递增版本会在读取时使其行失效；该 key 从日志重新折叠。
+- **整记录写入。** 每次写入替换该会话的完整检查点（注册表切面始终是完整的），并经无损 JSON 边界快照——违反纯 JSON 契约的单元状态会大声失败。
+- **记录绑定到日志生命周期，而不只是 id。** 每条记录存储其折叠来源的 header 身份（`createdAt`、`cwd`）；每次读取先以活 header 或存储 header 为证验证它,再接受任何行——被删后重建的 id、或缓存幸存而持久化存储被换掉时,无关记录被整体丢弃,绝不播种幻影值。
+- **日志领先，缓存跟随。** 活会话检查点先把缓冲事件持久 flush,缓存行才落地,因此崩溃只会让缓存落后于日志（更长的尾部重放）,绝不领先于它。
+
+## 写策略
+
+两个必写点，其间节流：
+
+| 触发 | 性质 |
+|---|---|
+| `turn/end` | 必写——冷读要的正是轮次终值。 |
+| 会话销毁（detach） | 必写——live 转 cold 的时刻；此后冷读阶梯接管该会话。 |
+| 累计 `writeEveryEvents` 个已提交事件 | 配置节流（条数）。 |
+| 距首个脏事件 `writeIntervalMs` 毫秒 | 配置节流（间隔）。 |
+
+两个 `Config` 字段均必填（无默认值）：写入节奏是部署选择，没有普适正确值，由 cordis.yml 明示。
+
+## 列表读（`cachedSnapshot(meta)`）
+
+零 I/O 一档：从身份匹配的存储记录直接 view 全量值（仅版本匹配的 key）,以 `{asOfSeq, values}` 切面返回——`asOfSeq` 取所服务行的最低水位,客户端在 higher-seq-wins 规则下播种值仓时,陈旧列表块永远压不过更新的推送帧。无可用记录（未知 id、无关生命周期、无版本匹配行）时返回 `undefined`；api-proxy 列表载体将其转为列缺席。
+
+## 冷读（`coldSnapshot(id, signal?)`）
+
+读取阶梯，快乐路径零全量日志加载：缓存行 → `sessionProjections.restoreFloor`（锚在最低可用水位下一格）→ 持久化 `readFrom(id, floor)` → `sessionProjections.restore` → 刷新行的 fail-soft 写回。这个锚使缩短的日志（崩溃修复截断）可被证明：越界的行恰好触发一次从 seq 0 的全量重读，而不是把幽灵值当现值服务。无已注册单元时直接服务 `{asOfSeq: -1, values: {}}`，不触碰持久化；无持久日志的会话以 seam 的 `not found` 拒绝。
+
+`write(session)` 是两个必写点共用的同步切面检查点；载体可以直接调用（非 fail-soft——由 fail-soft 包装层负责遏制）。
+
+## 组合
+
+```yaml
+- id: session-projection-cache
+  name: '@deepseek-ai/dsh-session-projection-cache'
+  config:
+    writeEveryEvents: 200
+    writeIntervalMs: 5000
+```
+
+注入 `storageDomain`、`sessionProjections`、`sessionPersistence`、`sessions`。没有这一行时，投影系统只跑 live（水位缓存；冷读在实现了它的载体处退回全量日志加载）。
+
+## 模型体验
+
+无，因为缓存只持久化并恢复 host 侧的、由已入日志会话状态派生的读模型，不触碰任何提示词、消息、schema、流或工具结果。
+
+#### KV 缓存影响
+
+无；缓存从不组装或发送提供方请求。
+
+## 已知局限与延后工作
+
+- **没有淘汰或保留面**——记录按会话累积；清理存储的检查点是带外维护，与会话持久化本身同一立场。
+- **间隔节流按会话粗粒度**——计时器在一次干净写入后的首个脏事件时武装；持续的低于阈值的涓流每个间隔写一次，不是滑动窗口。
+- **`coldSnapshot` 读取不去重**——同一会话的两个并发冷读各跑一遍阶梯；写回最后者胜（行等价），对列表级调用频率可接受。

packages/session-projection/session-projection-cache/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@deepseek-ai/dsh-session-projection-cache",
+  "description": "Persisted projection cache (ctx.sessionProjectionCache): durable per-session projection checkpoints over the domain data form, throttled write-behind, and the cold-read ladder (cache row + persistence tail replay)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "schemastery": "^3.18.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "@deepseek-ai/dsh-storage-domain": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/session-projection/session-projection-cache/src/index.ts

@@ -0,0 +1,300 @@
+/**
+ * Persisted projection cache (`ctx.sessionProjectionCache`): durable
+ * checkpoints of every registered projection unit's state, one record per
+ * session on the domain data form (`session_projcache` domain — the shipped
+ * json backend lands it beside `workspace.json`). The cache is a fold
+ * shortcut, never an authority: a row is possibly stale (its `seq`
+ * says how stale) but never wrong, so every write path is fail-soft (a lost
+ * write costs a longer tail replay on the next cold read) and a
+ * `ver` mismatch discards the row instead of migrating it. Design
+ * authority: the session-projection RFC
+ * (.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
+ * @module @deepseek-ai/dsh-session-projection-cache
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+// Empty type import: applies the package's cordis Context merge
+// (`ctx.sessionPersistence`), which this service reads on the cold path.
+import type {} from '@deepseek-ai/dsh-session-persistence'
+import type { ProjectionCheckpoint, ProjectionSnapshot } from '@deepseek-ai/dsh-session-projection'
+import type { KvTable } from '@deepseek-ai/dsh-storage-domain'
+import { projectionCacheDomainSpec } from './spec.ts'
+import type { CheckpointIdentity, CheckpointRecord } from './spec.ts'
+
+export { checkpointIdentity, checkpointRecord, checkpointRow, projectionCacheDomainSpec } from './spec.ts'
+export type { CheckpointIdentity, CheckpointRecord } from './spec.ts'
+
+declare module 'cordis' {
+  interface Context {
+    sessionProjectionCache: SessionProjectionCache
+  }
+}
+
+/**
+ * Plugin config. Both throttle triggers are deployment choices with no
+ * universally correct value, so the composition states them explicitly
+ * (cordis.yml); the two mandatory write points (`turn/end` and session
+ * disposal) are policy, not tunables, and always fire.
+ */
+export interface Config {
+  /** Committed events per session that force a durable checkpoint write between mandatory points. */
+  writeEveryEvents: number
+  /** Longest time (milliseconds) a dirty checkpoint may stay unwritten between mandatory points. */
+  writeIntervalMs: number
+}
+
+export const Config: z<Config> = z.object({
+  writeEveryEvents: z.natural().min(1).required(),
+  writeIntervalMs: z.natural().min(1).required(),
+})
+
+/** Per-session write-behind bookkeeping (live sessions only; dropped at retire). */
+interface DirtyState {
+  /** Committed events since the last durable write. */
+  pending: number
+  /** Interval trigger armed at the first dirty event after a clean write. */
+  timer: ReturnType<typeof setTimeout> | undefined
+}
+
+/**
+ * The persisted projection cache service. Opens the `session_projcache`
+ * domain at init, checkpoints live sessions on a throttled write-behind
+ * (count/interval triggers from {@link Config}) plus two mandatory points —
+ * `turn/end` and session disposal (the live-to-cold moment) — and serves the
+ * cold-read ladder: cached row, persistence `readFrom` tail, registry
+ * `restore`, durable write-back. Every durable write is fail-soft: failures
+ * log a warning and the cache self-heals on the next write or cold read.
+ */
+export class SessionProjectionCache extends Service {
+  static inject = ['storageDomain', 'sessionProjections', 'sessionPersistence', 'sessions']
+
+  static Config: z<Config> = Config
+
+  private table?: KvTable<SessionId, CheckpointRecord>
+  private readonly dirty = new Map<Session, DirtyState>()
+
+  constructor(ctx: Context, public config: Config) {
+    super(ctx, 'sessionProjectionCache')
+  }
+
+  /** Open the domain and install the write-behind listeners. */
+  protected async [Service.init](): Promise<void> {
+    const domain = await this.ctx.storageDomain.open(projectionCacheDomainSpec)
+    this.ctx.effect(() => () => domain.close(), 'sessionProjectionCache.domainClose')
+    this.table = domain.table('sessions')
+    this.installWritePath()
+  }
+
+  /**
+   * The stored record for one session, accepted only when its bound log
+   * identity matches `expected`. A session id names a slot, not a lifecycle:
+   * a recreated id or a persistence store swapped under a surviving cache
+   * must not let an old record seed state folded from an unrelated log.
+   * Synchronous from the domain's in-memory state.
+   * @param id - the session whose record is read.
+   * @param expected - the log identity the caller holds (live or stored header).
+   * @returns the identity-matching record, or `undefined` (absent or unrelated).
+   */
+  private recordFor(id: SessionId, expected: CheckpointIdentity): CheckpointRecord | undefined {
+    const record = this.requireTable().get(id)
+    if (record === undefined) return undefined
+    return identityMatches(record.identity, expected) ? record : undefined
+  }
+
+  /**
+   * The zero-I/O listing read: whole values viewed straight from the stored
+   * rows (version-matching keys only), each cut carried with its watermark
+   * so a client value store can seed under its higher-seq-wins rule — as
+   * stale as the last durable checkpoint but never wrong, and never from an
+   * unrelated log (the caller's header is the identity witness). Fresher
+   * paths (the history tail baseline, {@link coldSnapshot}) supersede these
+   * values whenever a session is actually opened.
+   * @param meta - the listed session's header (identity witness; no log read).
+   * @returns the cut (`asOfSeq` = lowest served-row watermark), or
+   *   `undefined` when no usable row exists for this lifecycle.
+   */
+  cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined {
+    const record = this.recordFor(meta.id, identityOf(meta))
+    if (record === undefined) return undefined
+    const values = this.ctx.sessionProjections.viewCheckpoint(record.rows)
+    const keys = Object.keys(values)
+    if (keys.length === 0) return undefined
+    // The block carries ONE cut: the lowest served watermark is the seq every
+    // value is at least current as of (under-claiming is safe under
+    // higher-seq-wins; over-claiming would let a stale value outrank pushes).
+    const asOfSeq = Math.min(...keys.map(key => (record.rows[key] as { seq: number }).seq))
+    return { asOfSeq, values }
+  }
+
+  /**
+   * Durably checkpoint one live session NOW (both mandatory points call
+   * this; tests and carriers may too). The registry cut is snapshotted at
+   * this boundary (states are live references), then the whole record is
+   * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
+   * @param session - the live session to checkpoint.
+   * @returns resolution after durability and event emission.
+   */
+  async write(session: Session): Promise<void> {
+    const rows = this.ctx.sessionProjections.checkpoint(session)
+    this.markClean(session)
+    // Durability barrier: the checkpoint cut was taken above, so flushing
+    // AFTER it guarantees every event inside the cut is durably logged
+    // before the cache row lands — a crash can leave the cache behind the
+    // log (longer tail replay) but never ahead of it (phantom values folded
+    // from events no stored log contains). At detach the store entry is
+    // already gone; persistence's own retirement drain covers that path and
+    // any residual overreach is caught by the cold read's anchored floor.
+    if (this.ctx.sessions.get(session.id) === session) await this.ctx.sessions.flush(session)
+    await this.put(session.id, identityOf(session.header), rows)
+  }
+
+  /**
+   * Cold-read one persisted session's projections with zero full-log load:
+   * cached rows + a persistence `readFrom` tail from the registry's restore
+   * floor, refolded by the registry and written back (fail-soft) so the next
+   * cold read starts closer. A cache row invalidated by a shrunk log
+   * (crash-repair truncation) triggers one full re-read from seq 0 — the
+   * ladder's slow rung, still no crash. Rejects when the session has no
+   * persisted log (`not found` from the persistence seam).
+   * @param id - the persisted session to read.
+   * @param signal - optional cancellation for the persistence reads.
+   * @returns the snapshot cut at the stored log end.
+   */
+  async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot> {
+    const record = this.requireTable().get(id)
+    const cached = record?.rows ?? {}
+    const floor = this.ctx.sessionProjections.restoreFloor(cached)
+    const persistence = this.ctx.sessionPersistence
+    if (floor === undefined) {
+      // No unit registered: nothing to fold, but the not-found contract must
+      // hold in this topology too — the probe read rejects for an absent log
+      // and dates the empty cut for a present one.
+      const probe = await persistence.readFrom(id, 0, signal)
+      return { asOfSeq: probe.events.at(-1)?.seq ?? -1, values: {} }
+    }
+    let restored: { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
+    const tail = await persistence.readFrom(id, floor, signal)
+    // The tail's stored header is the identity witness: a record bound to a
+    // different lifecycle (recreated id, swapped store) is discarded whole
+    // before any of its rows can seed a fold.
+    const related = record === undefined || identityMatches(record.identity, identityOf(tail.meta))
+    try {
+      if (!related) throw new Error('unrelated log identity')
+      restored = this.ctx.sessionProjections.restore(cached, tail.events, floor)
+    } catch {
+      // The recoverable restore failures: an unrelated record, or a row
+      // overreaching the stored log end (or predating the floor). Both imply
+      // floor > 0 (baseSeq-0 restores never throw and an unrelated record
+      // still carried a usable watermark), so the full log is a fresh read.
+      const whole = await persistence.readFrom(id, 0, signal)
+      restored = this.ctx.sessionProjections.restore({}, whole.events, 0)
+    }
+    await this.putSoft(id, identityOf(tail.meta), restored.checkpoint, 'cold-read write-back')
+    return restored.snapshot
+  }
+
+  // --- write-behind (throttle + mandatory points) ---
+
+  private installWritePath(): void {
+    // Every committed event advances the dirty counter; turn/end is a
+    // mandatory point (the durable value most reads want is the turn-final
+    // one), count/interval throttle the in-turn stream.
+    this.ctx.on('session/event', (session: Session, event: SessionEvent) => {
+      if (event.type === 'turn/end') {
+        void this.flushSoft(session, 'turn/end')
+        return
+      }
+      const state = this.dirty.get(session) ?? { pending: 0, timer: undefined }
+      this.dirty.set(session, state)
+      state.pending += 1
+      if (state.pending >= this.config.writeEveryEvents) {
+        void this.flushSoft(session, 'count threshold')
+        return
+      }
+      state.timer ??= setTimeout(() => {
+        void this.flushSoft(session, 'interval')
+      }, this.config.writeIntervalMs)
+    })
+
+    // Detach (the live-to-cold moment): the second mandatory point. After
+    // this write the cold-read ladder serves the session from the cache.
+    // flushSoft's synchronous prefix reads and resets the dirty state, so
+    // dropping it (timer already cleared by markClean) right after is safe.
+    this.ctx.on('session/disposed', (session: Session) => {
+      void this.flushSoft(session, 'detach')
+      this.markClean(session)
+      this.dirty.delete(session)
+    })
+
+    // Clear pending timers with the plugin (their sessions outlive the cache).
+    this.ctx.effect(() => () => {
+      for (const state of this.dirty.values()) {
+        if (state.timer !== undefined) clearTimeout(state.timer)
+      }
+      this.dirty.clear()
+    }, 'sessionProjectionCache.timers')
+  }
+
+  /**
+   * One fail-soft durable checkpoint. Every caller has work by construction:
+   * the throttle triggers only fire dirty (markClean clears the timer with
+   * the counter) and the two mandatory points write unconditionally.
+   */
+  private async flushSoft(session: Session, trigger: string): Promise<void> {
+    try {
+      await this.write(session)
+    } catch (error) {
+      this.ctx.logger.warn(`session projection cache: ${trigger} write for "${session.id}" failed (cache stays stale): ${String(error)}`)
+    }
+  }
+
+  /** Reset one session's dirty bookkeeping (its checkpoint is being written). */
+  private markClean(session: Session): void {
+    const state = this.dirty.get(session)
+    if (state === undefined) return
+    state.pending = 0
+    if (state.timer !== undefined) {
+      clearTimeout(state.timer)
+      state.timer = undefined
+    }
+  }
+
+  /** Replace one session's stored record with its log identity and a detached snapshot of `rows`. */
+  private async put(id: SessionId, identity: CheckpointIdentity, rows: ProjectionCheckpoint): Promise<void> {
+    const detached = snapshotJsonValue(rows)
+    if (detached === undefined) {
+      throw new TypeError('projection checkpoint is not losslessly JSON-serializable (a unit state violates the plain-JSON contract)')
+    }
+    await this.requireTable().put(id, { identity, rows: detached as CheckpointRecord['rows'] })
+  }
+
+  /** Fail-soft {@link put}: cache writes must never fail their caller's read or event path. */
+  private async putSoft(id: SessionId, identity: CheckpointIdentity, rows: ProjectionCheckpoint, what: string): Promise<void> {
+    try {
+      await this.put(id, identity, rows)
+    } catch (error) {
+      this.ctx.logger.warn(`session projection cache: ${what} for "${id}" failed (cache stays stale): ${String(error)}`)
+    }
+  }
+
+  private requireTable(): KvTable<SessionId, CheckpointRecord> {
+    /* v8 ignore next -- Service.init assigns the table before the service becomes injectable */
+    if (this.table === undefined) throw new Error('session projection cache is not initialized')
+    return this.table
+  }
+}
+
+/** Project a header onto the identity fields a record is bound to. */
+function identityOf(header: SessionHeader): CheckpointIdentity {
+  return { createdAt: header.createdAt, ...header.cwd === undefined ? {} : { cwd: header.cwd } }
+}
+
+/** Whether a stored record's bound identity names the caller's lifecycle. */
+function identityMatches(stored: CheckpointIdentity, expected: CheckpointIdentity): boolean {
+  return stored.createdAt === expected.createdAt && stored.cwd === expected.cwd
+}
+
+export default SessionProjectionCache

packages/session-projection/session-projection-cache/src/invariant.ts

@@ -0,0 +1,35 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-projection-cache`.
+ * @module @deepseek-ai/dsh-session-projection-cache/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-projection-cache'
+
+/** Cordis companion plugin name. */
+export const name = 'session-projection-cache-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the cache's correctness relation (a stored row equals
+ * the registry fold at its `seq` watermark) is only checkable by re-running the
+ * fold over the persisted log — duplicating the implementation rather than
+ * detecting drift — and its staleness is by design (fail-soft writes). The
+ * durable boundary is already schema-validated by the storage-domain layer
+ * on every reopen, and the read ladder's version/watermark guards are proven
+ * by the package spec.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/session-projection/session-projection-cache/src/spec.ts

@@ -0,0 +1,71 @@
+/**
+ * The session-projcache domain declaration: one `sessions` table keyed by
+ * {@link SessionId}, each record the full projection checkpoint for one
+ * session (`key → {ver, seq, val}` rows). The spec object
+ * is the single source of the domain's identity, version, and record schema;
+ * the storage-domain routing decides the medium (the shipped composition's
+ * json backend lands it at `<root>/session_projcache.json`, beside
+ * `workspace.json`).
+ * @module @deepseek-ai/dsh-session-projection-cache/src/spec
+ */
+
+import { z } from 'zod'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+
+/**
+ * One persisted checkpoint row (the RFC's `(sessionId, key, ver, seq, val)`
+ * minus the two record keys). `val` is the unit's internal state — plain
+ * JSON by the unit contract; `z.json()` enforces that at the durable
+ * boundary. A row is never wrong, only possibly stale: `seq` says exactly
+ * how stale, and a `ver` mismatch against the live unit's `stateVersion`
+ * discards it at read time (never a migration).
+ */
+export const checkpointRow = z.object({
+  ver: z.number().int().nonnegative(),
+  seq: z.number().int().gte(-1),
+  val: z.json(),
+})
+
+/**
+ * The stored-log identity a record is bound to: the immutable header fields
+ * that distinguish one session lifecycle from another under the same id. A
+ * session id names a slot, not a lifecycle — a deleted-then-recreated id, or
+ * a persistence root swapped under a surviving cache, would otherwise let an
+ * old row pass every watermark check and seed state folded from an unrelated
+ * log. Reads validate this against the live header (listing) or the stored
+ * header (cold read) before accepting any row.
+ */
+export const checkpointIdentity = z.object({
+  createdAt: z.number().int().nonnegative(),
+  cwd: z.string().optional(),
+})
+
+/** The identity fields a record is bound to, inferred from {@link checkpointIdentity}. */
+export type CheckpointIdentity = z.infer<typeof checkpointIdentity>
+
+/**
+ * One session's stored record: the log identity it was folded from plus its
+ * checkpoint rows keyed by projection key. The whole record is replaced on
+ * every write (whole-value discipline — the registry checkpoint is always
+ * the complete per-session cut).
+ */
+export const checkpointRecord = z.object({
+  identity: checkpointIdentity,
+  rows: z.record(z.string(), checkpointRow),
+})
+
+/** One stored per-session checkpoint record, inferred from {@link checkpointRecord}. */
+export type CheckpointRecord = z.infer<typeof checkpointRecord>
+
+/**
+ * The session-projcache domain spec. Version bumps discard the whole medium
+ * (cache semantics: a stale or unreadable cache costs a longer tail replay,
+ * never a wrong value). v2 added the record's log-identity binding; v3
+ * renamed the row fields to `ver`/`seq`/`val`.
+ */
+export const projectionCacheDomainSpec = defineDomain({
+  name: 'session_projcache',
+  version: 3,
+  tables: { sessions: domainTable<SessionId, CheckpointRecord>(checkpointRecord) },
+})

packages/session-projection/session-projection-cache/tests/cache.spec.ts

@@ -0,0 +1,387 @@
+/**
+ * SessionProjectionCache behavior: mandatory-point writes (turn/end, detach),
+ * count/interval throttling between them, fail-soft durability (a failed
+ * write logs and stays stale, never throws into the event path), and the
+ * cold-read ladder (cached row + readFrom tail + registry restore +
+ * write-back; version bump and shrunk-log rows degrade to a full re-read).
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { z } from 'zod'
+import Storage from '@deepseek-ai/dsh-storage'
+import { DomainFacility } from '@deepseek-ai/dsh-storage-domain'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import { MemoryMediaPool, MemoryStorageBackend } from '../../../storage/storage-domain/tests/helpers/memory-backend.ts'
+import SessionProjectionCache from '../src/index.ts'
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    'cache-test/marks': { marks: string[] }
+  }
+}
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    'cache-test/mark': { marks: string[] }
+  }
+
+  interface OutOfBandSessionEventMap {
+    'cache-test/mark': true
+  }
+}
+
+type MarksState = { marks: string[] } | null
+const marksUnit = (stateVersion = 1): ProjectionDefinition<'cache-test/marks', MarksState> => ({
+  key: 'cache-test/marks',
+  schema: z.object({ marks: z.array(z.string()) }),
+  init: () => null,
+  apply: (state, event) => (event.type === 'cache-test/mark' ? (event).data : state),
+  view: state => state ?? { marks: [] },
+  stateVersion,
+})
+
+/** A persistence double serving readFrom over a fixed per-id stored log (headers stamp createdAt 0). */
+function fakePersistence(logs: Map<string, SessionEvent[]>) {
+  const readFrom = vi.fn(async (id: SessionId, fromSeq: number) => {
+    const events = logs.get(String(id))
+    if (events === undefined) throw new Error(`session "${id}" not found`)
+    return {
+      meta: { version: 0, id, createdAt: 0 },
+      events: events.filter(event => event.seq >= fromSeq),
+    }
+  })
+  return { readFrom }
+}
+
+/** Header shape for cachedSnapshot calls (fake logs stamp createdAt 0, no cwd). */
+const headerOf = (id: SessionId, createdAt = 0, cwd?: string) =>
+  ({ version: 0, id, createdAt, ...cwd === undefined ? {} : { cwd } })
+
+interface HarnessOptions {
+  pool?: MemoryMediaPool
+  config?: { writeEveryEvents: number; writeIntervalMs: number }
+  stateVersion?: number
+  logs?: Map<string, SessionEvent[]>
+}
+
+const contexts: Context[] = []
+
+async function harness(options: HarnessOptions = {}) {
+  const pool = options.pool ?? new MemoryMediaPool()
+  const logs = options.logs ?? new Map<string, SessionEvent[]>()
+  const ctx = new Context()
+  contexts.push(ctx)
+  await ctx.plugin(Storage)
+  ctx.storage.backend.register('memory', new MemoryStorageBackend(pool))
+  const facility = new DomainFacility(ctx, { backend: 'memory', routes: {} })
+  ctx.storage.mount('domain', facility)
+  ctx.provide('storageDomain', facility)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionProjectionRegistry)
+  ctx.sessionProjections.register(marksUnit(options.stateVersion))
+  const persistence = fakePersistence(logs)
+  ctx.provide('sessionPersistence', persistence as never)
+  const fiber = await ctx.plugin(SessionProjectionCache, options.config ?? { writeEveryEvents: 100, writeIntervalMs: 60_000 })
+  return { ctx, pool, logs, fiber, persistence, cache: ctx.sessionProjectionCache }
+}
+
+const mark = (session: Session, marks: string[]): SessionEvent =>
+  session.append('cache-test/mark', { marks })
+
+const endTurn = (session: Session): SessionEvent =>
+  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+/** The stored medium record for one session id (undefined = never written). */
+function storedRecord(pool: MemoryMediaPool, id: Session['id']) {
+  return pool.media.get('session_projcache')?.tables.get('sessions')?.get(String(id)) as
+    {
+      identity: { createdAt: number; cwd?: string }
+      rows: Record<string, { ver: number; seq: number; val: unknown }>
+    } | undefined
+}
+
+/** The stored medium rows for one session id (undefined = never written). */
+function storedRows(pool: MemoryMediaPool, id: Session['id']) {
+  return storedRecord(pool, id)?.rows
+}
+
+/** Wait until queued fail-soft writes (event-listener fire-and-forget) drain. */
+const settle = () => new Promise(resolve => setTimeout(resolve, 0))
+
+afterEach(async () => {
+  vi.useRealTimers()
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+})
+
+describe('SessionProjectionCache write policy', () => {
+  it('writes a durable checkpoint at turn/end (mandatory point)', async () => {
+    const { ctx, pool } = await harness()
+    const session = ctx.sessions.create(SessionId('turn-end'))
+    mark(session, ['a'])
+    expect(storedRows(pool, session.id)).toBeUndefined() // throttled: no write yet
+    const end = endTurn(session)
+    await settle()
+    const rows = storedRows(pool, session.id)
+    expect(rows?.['cache-test/marks']).toEqual({ ver: 1, seq: end.seq, val: { marks: ['a'] } })
+  })
+
+  it('writes at session disposal (detach, the live-to-cold moment)', async () => {
+    const { ctx, pool } = await harness()
+    // Sessions dispose with their owning fiber: create in a child plugin.
+    let session: Session | undefined
+    const owner = await ctx.plugin(Object.assign((inner: Context) => {
+      session = inner.sessions.create(SessionId('detach'))
+    }, { inject: ['sessions'] }))
+    if (session === undefined) throw new Error('session was not created')
+    mark(session, ['live'])
+    await owner.dispose()
+    await settle()
+    expect(storedRows(pool, session.id)?.['cache-test/marks']?.val).toEqual({ marks: ['live'] })
+  })
+
+  it('flushes when the in-turn event count reaches the configured threshold', async () => {
+    const { ctx, pool } = await harness({ config: { writeEveryEvents: 3, writeIntervalMs: 60_000 } })
+    const session = ctx.sessions.create(SessionId('count'))
+    mark(session, ['1'])
+    mark(session, ['2'])
+    await settle()
+    expect(storedRows(pool, session.id)).toBeUndefined()
+    mark(session, ['3'])
+    await settle()
+    expect(storedRows(pool, session.id)?.['cache-test/marks']?.val).toEqual({ marks: ['3'] })
+  })
+
+  it('flushes on the configured interval when the count threshold is not reached', async () => {
+    vi.useFakeTimers()
+    const { ctx, pool } = await harness({ config: { writeEveryEvents: 100, writeIntervalMs: 250 } })
+    const session = ctx.sessions.create(SessionId('interval'))
+    mark(session, ['slow'])
+    await vi.advanceTimersByTimeAsync(249)
+    expect(storedRows(pool, session.id)).toBeUndefined()
+    await vi.advanceTimersByTimeAsync(1)
+    await vi.advanceTimersByTimeAsync(0)
+    expect(storedRows(pool, session.id)?.['cache-test/marks']?.val).toEqual({ marks: ['slow'] })
+  })
+
+  it('write() on a never-dirty session checkpoints directly and rejects a non-JSON unit state', async () => {
+    const { ctx, pool } = await harness()
+    // Never dirtied: no events — write() still lands the init-derived cut.
+    const clean = ctx.sessions.create(SessionId('clean-write'))
+    await ctx.sessionProjectionCache.write(clean)
+    expect(storedRows(pool, clean.id)?.['cache-test/marks']).toEqual({ ver: 1, seq: -1, val: null })
+    // A unit whose state violates the plain-JSON contract fails the write loud.
+    ctx.sessionProjections.register({
+      key: 'cache-test/marks2' as never,
+      schema: { parse: (value: unknown) => value } as never,
+      init: () => new Map<string, string>(),
+      apply: (state: unknown) => state,
+      view: () => null as never,
+      stateVersion: 1,
+    })
+    await expect(ctx.sessionProjectionCache.write(clean)).rejects.toThrow('not losslessly JSON-serializable')
+  })
+
+  it('plugin disposal clears armed interval timers and leaves cleaned sessions alone', async () => {
+    vi.useFakeTimers()
+    const { ctx, pool, fiber } = await harness({ config: { writeEveryEvents: 100, writeIntervalMs: 5000 } })
+    const armed = ctx.sessions.create(SessionId('armed'))
+    const cleaned = ctx.sessions.create(SessionId('cleaned'))
+    mark(armed, ['pending']) // timer armed, no write yet
+    mark(cleaned, ['done'])
+    endTurn(cleaned) // mandatory write; markClean leaves {pending: 0, timer: undefined} in the map
+    await vi.advanceTimersByTimeAsync(0)
+    await fiber.dispose()
+    // The armed timer died with the plugin: advancing time writes nothing.
+    await vi.advanceTimersByTimeAsync(10_000)
+    expect(storedRows(pool, armed.id)).toBeUndefined()
+  })
+
+  it('contains a durable write failure: logs a warning, event path unharmed, next write self-heals', async () => {
+    const { ctx, pool } = await harness()
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    const session = ctx.sessions.create(SessionId('fail-soft'))
+    mark(session, ['x'])
+    pool.failNextWrites = 1
+    endTurn(session)
+    await settle()
+    expect(storedRows(pool, session.id)).toBeUndefined()
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('turn/end write for "fail-soft" failed'))
+    // Self-heal: the next mandatory point writes the current cut.
+    mark(session, ['y'])
+    endTurn(session)
+    await settle()
+    expect(storedRows(pool, session.id)?.['cache-test/marks']?.val).toEqual({ marks: ['y'] })
+  })
+})
+
+describe('SessionProjectionCache cold read', () => {
+  const storedLog = (marks: string[][]): SessionEvent[] => {
+    const events: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    ]
+    for (const m of marks) {
+      events.push({ type: 'cache-test/mark', seq: events.length, time: events.length, data: { marks: m } })
+    }
+    events.push({ type: 'turn/end', seq: events.length, time: events.length, data: { turn: 1, reason: { kind: 'completed' } } })
+    return events
+  }
+
+  /** Pre-seed the medium with one stored checkpoint record (before the domain opens). */
+  function seedRow(
+    pool: MemoryMediaPool,
+    id: string,
+    row: { ver: number; seq: number; val: unknown },
+    identity: { createdAt: number; cwd?: string } = { createdAt: 0 },
+  ): void {
+    pool.versions.set('session_projcache', 3)
+    pool.media.set('session_projcache', {
+      tables: new Map([['sessions', new Map([[id, { identity, rows: { 'cache-test/marks': row } }]])]]),
+      global: null,
+    })
+  }
+
+  it('serves a cold session from the cache row plus a bounded tail read, and writes the refresh back', async () => {
+    const pool = new MemoryMediaPool()
+    const logs = new Map([['cold', storedLog([['a'], ['a', 'b']])]])
+    // A warm-era checkpoint at watermark 1 (only ['a'] folded).
+    seedRow(pool, 'cold', { ver: 1, seq: 1, val: { marks: ['a'] } })
+    const { cache, persistence, pool: samePool } = await harness({ pool, logs })
+    const id = SessionId('cold')
+    const snapshot = await cache.coldSnapshot(id)
+    expect(snapshot.values['cache-test/marks']).toEqual({ marks: ['a', 'b'] })
+    expect(snapshot.asOfSeq).toBe(3)
+    // The tail read was bounded by the anchored floor (watermark 1 -> floor 1), not 0.
+    expect(persistence.readFrom).toHaveBeenCalledWith(id, 1, undefined)
+    // Write-back: the stored row advanced to the served cut.
+    expect(storedRows(samePool, id)?.['cache-test/marks'])
+      .toEqual({ ver: 1, seq: 3, val: { marks: ['a', 'b'] } })
+  })
+
+  it('discards a version-mismatched row and refolds the full log', async () => {
+    const pool = new MemoryMediaPool()
+    const logs = new Map([['bumped', storedLog([['a']])]])
+    seedRow(pool, 'bumped', { ver: 1, seq: 2, val: { marks: ['stale'] } })
+    const { cache, persistence } = await harness({ pool, logs, stateVersion: 2 })
+    const snapshot = await cache.coldSnapshot(SessionId('bumped'))
+    expect(snapshot.values['cache-test/marks']).toEqual({ marks: ['a'] })
+    // Mismatch pulls the floor to 0: one full read, no second pass needed.
+    expect(persistence.readFrom).toHaveBeenCalledTimes(1)
+    expect(persistence.readFrom).toHaveBeenCalledWith(SessionId('bumped'), 0, undefined)
+  })
+
+  it('detects a log shrunk below the row watermark and degrades to one full re-read', async () => {
+    const pool = new MemoryMediaPool()
+    const logs = new Map([['shrunk', storedLog([['a']])]]) // seqs 0..2
+    seedRow(pool, 'shrunk', { ver: 1, seq: 9, val: { marks: ['ghost'] } })
+    const { cache, persistence } = await harness({ pool, logs })
+    const snapshot = await cache.coldSnapshot(SessionId('shrunk'))
+    expect(snapshot.values['cache-test/marks']).toEqual({ marks: ['a'] })
+    expect(snapshot.asOfSeq).toBe(2)
+    // Anchored tail read (floor 9) came back empty -> full re-read from 0.
+    expect(persistence.readFrom).toHaveBeenNthCalledWith(1, SessionId('shrunk'), 9, undefined)
+    expect(persistence.readFrom).toHaveBeenNthCalledWith(2, SessionId('shrunk'), 0, undefined)
+  })
+
+  it('write-back failure is contained: the snapshot is still served', async () => {
+    const pool = new MemoryMediaPool()
+    const logs = new Map([['soft', storedLog([['a']])]])
+    const { ctx, cache } = await harness({ pool, logs })
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    pool.failNextWrites = 1
+    const snapshot = await cache.coldSnapshot(SessionId('soft'))
+    expect(snapshot.values['cache-test/marks']).toEqual({ marks: ['a'] })
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('cold-read write-back for "soft" failed'))
+  })
+
+  it('rejects for a session with no persisted log', async () => {
+    const { cache } = await harness()
+    await expect(cache.coldSnapshot(SessionId('absent'))).rejects.toThrow('not found')
+  })
+
+  it('discards a record bound to a different log lifecycle and refolds from the actual log', async () => {
+    const pool = new MemoryMediaPool()
+    const logs = new Map([['reborn', storedLog([['real']])]]) // stored header stamps createdAt 0
+    // A checkpoint from a PRIOR lifecycle of the same id (different createdAt):
+    // its rows pass every watermark check, but the identity does not match.
+    seedRow(pool, 'reborn', { ver: 1, seq: 2, val: { marks: ['phantom'] } }, { createdAt: 999 })
+    const { cache, pool: samePool } = await harness({ pool, logs })
+    const snapshot = await cache.coldSnapshot(SessionId('reborn'))
+    expect(snapshot.values['cache-test/marks']).toEqual({ marks: ['real'] })
+    // The write-back rebinds the record to the actual log's identity.
+    expect(storedRecord(samePool, SessionId('reborn'))?.identity).toEqual({ createdAt: 0 })
+  })
+
+  it('cachedSnapshot returns undefined when every stored row is version-mismatched', async () => {
+    const pool = new MemoryMediaPool()
+    seedRow(pool, 'all-stale', { ver: 99, seq: 4, val: { marks: ['old'] } })
+    const { cache } = await harness({ pool })
+    expect(cache.cachedSnapshot(headerOf(SessionId('all-stale')))).toBeUndefined()
+  })
+
+  it('binds identity on cwd too: a matching cwd serves, a moved session does not', async () => {
+    const pool = new MemoryMediaPool()
+    seedRow(pool, 'homed', { ver: 1, seq: 2, val: { marks: ['w'] } }, { createdAt: 0, cwd: '/work' })
+    const { cache } = await harness({ pool })
+    const id = SessionId('homed')
+    expect(cache.cachedSnapshot(headerOf(id, 0, '/work'))?.values['cache-test/marks']).toEqual({ marks: ['w'] })
+    expect(cache.cachedSnapshot(headerOf(id, 0, '/elsewhere'))).toBeUndefined()
+    expect(cache.cachedSnapshot(headerOf(id, 0))).toBeUndefined()
+  })
+
+  it('dates an empty stored log at -1 in the zero-units topology', async () => {
+    const pool = new MemoryMediaPool()
+    const logs = new Map([['empty', [] as SessionEvent[]]])
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(Storage)
+    ctx.storage.backend.register('memory', new MemoryStorageBackend(pool))
+    const facility = new DomainFacility(ctx, { backend: 'memory', routes: {} })
+    ctx.storage.mount('domain', facility)
+    ctx.provide('storageDomain', facility)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionProjectionRegistry)
+    ctx.provide('sessionPersistence', fakePersistence(logs) as never)
+    await ctx.plugin(SessionProjectionCache, { writeEveryEvents: 100, writeIntervalMs: 60_000 })
+    await expect(ctx.sessionProjectionCache.coldSnapshot(SessionId('empty')))
+      .resolves.toEqual({ asOfSeq: -1, values: {} })
+  })
+
+  it('cachedSnapshot serves identity-matching rows with the cut watermark and refuses unrelated ones', async () => {
+    const pool = new MemoryMediaPool()
+    seedRow(pool, 'listed', { ver: 1, seq: 4, val: { marks: ['t'] } })
+    const { cache } = await harness({ pool })
+    const id = SessionId('listed')
+    // Matching header: values plus the watermark the client seeds under.
+    expect(cache.cachedSnapshot(headerOf(id))).toEqual({ asOfSeq: 4, values: { 'cache-test/marks': { marks: ['t'] } } })
+    // A recreated id (different createdAt): the record is unrelated — no block.
+    expect(cache.cachedSnapshot(headerOf(id, 777))).toBeUndefined()
+    // Unknown id: no block.
+    expect(cache.cachedSnapshot(headerOf(SessionId('never-cached')))).toBeUndefined()
+  })
+
+  it('holds the not-found contract with zero registered units, and dates the empty cut for a present log', async () => {
+    // Same composition minus any registered unit: restoreFloor is undefined,
+    // yet coldSnapshot must still reject for an absent log (probe read) and
+    // serve an empty cut at the stored end for a present one.
+    const pool = new MemoryMediaPool()
+    const logs = new Map([['bare', storedLog([['a']])]]) // seqs 0..2
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(Storage)
+    ctx.storage.backend.register('memory', new MemoryStorageBackend(pool))
+    const facility = new DomainFacility(ctx, { backend: 'memory', routes: {} })
+    ctx.storage.mount('domain', facility)
+    ctx.provide('storageDomain', facility)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionProjectionRegistry)
+    ctx.provide('sessionPersistence', fakePersistence(logs) as never)
+    await ctx.plugin(SessionProjectionCache, { writeEveryEvents: 100, writeIntervalMs: 60_000 })
+    await expect(ctx.sessionProjectionCache.coldSnapshot(SessionId('absent'))).rejects.toThrow('not found')
+    await expect(ctx.sessionProjectionCache.coldSnapshot(SessionId('bare')))
+      .resolves.toEqual({ asOfSeq: 2, values: {} })
+  })
+})

packages/session-projection/session-projection-cache/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../session-persistence/session-persistence"
+    },
+    {
+      "path": "../session-projection"
+    },
+    {
+      "path": "../../storage/storage"
+    },
+    {
+      "path": "../../storage/storage-domain"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/session-projection/session-projection/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session-projection/session-projection/README.md
-README.md: 2e026aab55933c96ba961481f9597bc18cbbe910
-README.zh.md: a3e0b0f46466d19321b0950dc41d06473a54a1ce
+README.md: f4898b8e567fa5998c18111c5f4e27a8a350a42e
+README.zh.md: 385862868df495a5c857d91c32f6503c3ef72025

packages/session-projection/session-projection/README.md

@@ -23,7 +23,7 @@ Session-projection seam. It owns `ctx.sessionProjections`, the registry that DRI
 - **Same-reference means no work.** `apply` MUST return the same state reference for events that do not concern the unit; the drive gates the change feed on `Object.is`, so non-matching events cost one call and nothing downstream.
 - **Whole-value event rule (load-bearing).** A state-carrying log event MUST carry the complete post-change state, never a bare delta — it keeps every transition trivially cheap and every served value self-describing (last-wins for consumers).
 - **Synchronous unit discipline.** `init`/`apply`/`view` MUST be synchronous; carriers read `snapshot()` in the same tick as their page slice, which is what makes `asOfSeq` one consistent cut. An accidentally-async `view` returns a Promise, which fails the boundary `schema.parse` loudly.
-- **State is plain JSON, `stateVersion` is its invalidation anchor.** The persisted projection cache (a later phase) stores `(sessionId, key, stateVersion, observedSeq, stateJson)` rows; bump `stateVersion` whenever the state shape or the fold semantics change so stale rows are discarded instead of forward-applied into garbage.
+- **State is plain JSON, `stateVersion` is its invalidation anchor.** The persisted projection cache stores `(sessionId, key, ver, seq, val)` rows; bump `stateVersion` whenever the state shape or the fold semantics change so stale rows are discarded instead of forward-applied into garbage.
 - **No wire vocabulary here.** The registry exposes only the change feed and the snapshot read face; carriers (api-proxy) mint their own frames (`session/projection`) and blocks from them.
 - **Optional seam.** Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected; carriers use `ctx.get('sessionProjections')` and omit their block/frames entirely when the registry is absent.
 
@@ -43,5 +43,5 @@ None; projections never assemble or send provider requests.
 
 - **Every tail page carries every registered key** — there is no per-key opt-out or lazy-key request shape yet; acceptable while values are UI-scale whole states (a todo list, a goal snapshot), revisit if a domain's value grows large.
 - **Eager drive touches every unit per event** — cheap by construction (whole-value rule, same-reference gate), but a hot path would justify per-unit event-type prefilters, addable without contract change.
-- **The persisted projection cache is a later phase** — cells live in memory only; a restart rebuilds by folding the in-memory log on first touch. The `stateVersion` field is the forward-declared invalidation anchor for that phase.
+- **Registry cells live in memory only** — a restart rebuilds by folding the log on first touch; compositions that mount `dsh-session-projection-cache` seed that fold from persisted rows instead.
 - **Synchronous unit discipline is only partially mechanical** — the boundary `schema.parse` rejects a Promise-returning `view`, but an `apply` that blocks or reads torn non-session state is a review concern; the invariant companion documents why no runtime check exists.

packages/session-projection/session-projection/README.zh.md

@@ -23,7 +23,7 @@
 - **同引用即无工作。** 对与单元无关的事件，`apply` 必须返回同一个状态引用；驱动以 `Object.is` 把守变更流，因此不匹配的事件只花一次调用，不产生任何下游工作。
 - **全量值事件规则（承重）。** 携带状态的日志事件必须携带变更后的完整状态，绝不携带裸增量——这让每次状态转移始终足够廉价，也让每个被供给的值自描述（对消费方即 last-wins）。
 - **单元的同步纪律。** `init`/`apply`/`view` 必须是同步的；载体在切出页面切片的同一 tick 内读取 `snapshot()`，`asOfSeq` 之所以是一个一致切面正系于此。误写成异步的 `view` 会返回 Promise，让边界的 `schema.parse` 当场大声失败。
-- **状态是纯 JSON，`stateVersion` 是其失效锚点。** 持久投影缓存（persisted projection cache，后续阶段）存储 `(sessionId, key, stateVersion, observedSeq, stateJson)` 行；状态形状或折叠语义一旦变化就递增 `stateVersion`，使陈旧行被丢弃，而不是被正向 apply 成垃圾。
+- **状态是纯 JSON，`stateVersion` 是其失效锚点。** 持久投影缓存（persisted projection cache）存储 `(sessionId, key, ver, seq, val)` 行；状态形状或折叠语义一旦变化就递增 `stateVersion`，使陈旧行被丢弃，而不是被正向 apply 成垃圾。
 - **本层没有协议词汇。** 注册表只暴露变更流与快照读取面；载体（api-proxy）据此自铸各自的帧（`session/projection`）与块。
 - **可选 seam。** 领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响；载体使用 `ctx.get('sessionProjections')`，注册表缺席时完全省略自己的块与帧。
 
@@ -43,5 +43,5 @@
 
 - **每个尾页携带每个已注册的 key**——尚无逐 key 的 opt-out 或惰性 key 请求形状；在值都是 UI 量级的全量状态（一张 todo 清单、一份 goal 快照）时可以接受，若某领域的值变大再重议。
 - **正向驱动（eager drive）逐事件触达每个单元**——按构造开销很低（全量值规则、同引用闸门），但若出现热点路径，可加按单元的事件类型预过滤，契约不变。
-- **持久投影缓存属于后续阶段**——cell 目前只活在内存里；重启后首次触达时靠折叠内存日志重建。`stateVersion` 字段是为该阶段预先声明的失效锚点。
+- **注册表 cell 只活在内存里**——重启后首次触达时靠折叠日志重建；挂载了 `dsh-session-projection-cache` 的组合改由持久行播种该折叠。
 - **单元同步纪律只有部分可机械把关**——边界 `schema.parse` 能拒绝返回 Promise 的 `view`，但阻塞的 `apply`、或读取撕裂的非会话状态的 `apply`，只能靠评审把关；invariant 配套记载了为何不存在运行时检查。

packages/session-projection/session-projection/src/index.ts

@@ -66,9 +66,9 @@ export interface ProjectionDefinition<K extends keyof SessionProjectionMap, S> {
   view(state: S): SessionProjectionMap[K]
   /**
    * Persisted-cache invalidation anchor: bump whenever the state shape or the
-   * fold semantics change, so persisted `(sessionId, key, stateVersion,
-   * observedSeq, state)` rows from an older unit are discarded instead of
-   * being forward-applied into garbage. Non-negative integer.
+   * fold semantics change, so persisted `(sessionId, key, ver, seq, val)`
+   * rows from an older unit are discarded instead of being forward-applied
+   * into garbage. Non-negative integer.
    */
   stateVersion: number
 }
@@ -97,6 +97,26 @@ export interface ProjectionSnapshot {
   values: Partial<SessionProjectionMap>
 }
 
+/**
+ * One unit's checkpoint: its internal state (plain JSON by the unit
+ * contract), the seq of the last event folded into it, and the unit
+ * `stateVersion` that produced it — the persisted projection-cache row
+ * `(sessionId, key, ver, seq, val)` minus the two outer keys. A row is
+ * never authoritative, only a fold shortcut: `restore` discards it on a
+ * version mismatch or when it claims events past the stored log end.
+ */
+export interface ProjectionCheckpointRow {
+  /** The registering unit's `stateVersion` at fold time. */
+  ver: number
+  /** Seq of the last event folded into `val`; -1 for the empty log. */
+  seq: number
+  /** The unit's internal state — plain JSON per the unit contract. */
+  val: unknown
+}
+
+/** Checkpoint rows keyed by projection key (one session's persisted cache value). */
+export type ProjectionCheckpoint = Record<string, ProjectionCheckpointRow>
+
 /** Type-erased unit view the drive machinery works with (the register seam already proved the typed contract). */
 interface ErasedDefinition {
   key: string
@@ -206,6 +226,136 @@ export class SessionProjectionRegistry extends Service {
     return { asOfSeq: session.seq - 1, values: values }
   }
 
+  /**
+   * State-level checkpoint of every registered unit for one session, read
+   * from the watermark cache (missing cells fold lazily over the in-memory
+   * log). This is the write side of the persisted projection cache: the
+   * returned rows are the `(key → {ver, seq, val})` part of the durable
+   * `(sessionId, key, ver, seq, val)`
+   * rows. Every `val` is a DETACHED structured clone — never the live
+   * cell reference: the watermark cache is this registry's authoritative
+   * mutable state, and a caller reaching the live reference could corrupt
+   * every subsequent snapshot and frame through it (plain JSON by the unit
+   * contract, so the clone is total).
+   * @param session - the session whose unit states are checkpointed.
+   * @returns one row per registered key; empty when no unit is registered.
+   */
+  checkpoint(session: Session): ProjectionCheckpoint {
+    const rows: ProjectionCheckpoint = {}
+    for (const registration of this.registrations.values()) {
+      const cell = this.cellFor(registration, session)
+      rows[registration.def.key] = {
+        ver: registration.def.stateVersion,
+        seq: cell.observedSeq,
+        val: structuredClone(cell.state),
+      }
+    }
+    return rows
+  }
+
+  /**
+   * The stored seq a {@link restore} tail read over `checkpoint` must start
+   * at: one event BELOW the lowest usable watermark (a row is usable when
+   * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+   * pulls the floor to `0` — that key must refold the full log). The
+   * one-below anchor is load-bearing: the tail then proves how far the
+   * stored log still extends, so {@link restore} can detect a log that
+   * shrank below a row's watermark (crash-repair truncation) instead of
+   * serving the stale row as current — an empty tail read from the anchor
+   * yields an end below every watermark and the restore rejects for a full
+   * re-read.
+   * @param checkpoint - persisted rows for one session (possibly stale or empty).
+   * @returns the seq to hand the persistence `readFrom`, or `undefined`
+   *   when no unit is registered (no read needed — {@link restore} would
+   *   serve empty values regardless).
+   */
+  restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined {
+    let floor: number | undefined
+    for (const registration of this.registrations.values()) {
+      const row = checkpoint[registration.def.key]
+      const need = row !== undefined && row.ver === registration.def.stateVersion
+        ? Math.max(row.seq + 1, 0)
+        : 0
+      floor = floor === undefined ? need : Math.min(floor, need)
+    }
+    return floor === undefined ? undefined : Math.max(floor - 1, 0)
+  }
+
+  /**
+   * View a checkpoint's rows without any log read: for every registered
+   * unit whose row's `ver` matches, serve the schema-validated
+   * `view` of the stored state; mismatched or absent rows leave their key
+   * absent (a cold or listing consumer treats it as not-yet-available and a
+   * fuller read path refolds it). The zero-I/O rung of the read ladder —
+   * values are as stale as their rows, never wrong.
+   * @param checkpoint - persisted rows for one session (possibly stale or empty).
+   * @returns whole values per key with a usable row; empty when none.
+   */
+  viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap> {
+    const values: Record<string, unknown> = {}
+    for (const registration of this.registrations.values()) {
+      const def = registration.def
+      const row = checkpoint[def.key]
+      if (row === undefined || row.ver !== def.stateVersion) continue
+      values[def.key] = def.schema.parse(def.view(row.val))
+    }
+    return values
+  }
+
+  /**
+   * Cold read: fold every registered unit over a stored log suffix, seeding
+   * each from its checkpoint row when usable — the one read recipe (cached
+   * state + forward tail replay + `view`) applied without a live `Session`.
+   * Call with the events returned by a persistence
+   * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+   * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+   * so a shrunk log is detected here. A row is usable iff its
+   * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+   * (`seq >= baseSeq - 1`), and it does not claim events past the
+   * supplied end (`seq <= endSeq`); an unusable row is discarded
+   * and its key refolds from `init` — which is only sound over the full
+   * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+   * from seq 0, e.g. after a crash-repair truncation shrank the log below
+   * a row's watermark).
+   * @param checkpoint - persisted rows for one session (possibly stale or empty).
+   * @param events - the stored events with `seq >= baseSeq`, in seq order.
+   * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+   * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+   *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+   *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+   */
+  restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number):
+  { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint } {
+    const endSeq = events.at(-1)?.seq ?? baseSeq - 1
+    const values: Record<string, unknown> = {}
+    const refreshed: ProjectionCheckpoint = {}
+    for (const registration of this.registrations.values()) {
+      const def = registration.def
+      const row = checkpoint[def.key]
+      const usable = row !== undefined
+        && row.ver === def.stateVersion
+        && row.seq >= baseSeq - 1
+        && row.seq <= endSeq
+      if (!usable && baseSeq > 0) {
+        throw new Error(
+          `session projection ${JSON.stringify(def.key)} cannot restore from seq ${baseSeq}: `
+          + 'its checkpoint row is missing, version-mismatched, or beyond the supplied log end; re-read from seq 0',
+        )
+      }
+      let state = usable ? row.val : def.init()
+      const from = usable ? row.seq : baseSeq - 1
+      for (const event of events) {
+        if (event.seq > from) state = def.apply(state, event)
+      }
+      values[def.key] = def.schema.parse(def.view(state))
+      refreshed[def.key] = { ver: def.stateVersion, seq: endSeq, val: state }
+    }
+    return {
+      snapshot: { asOfSeq: endSeq, values: values },
+      checkpoint: refreshed,
+    }
+  }
+
   /** Fold one unit from init over `events`, producing a cell watermarked at the last folded event. */
   private buildCell(def: ErasedDefinition, events: readonly SessionEvent[]): UnitCell {
     let state = def.init()

packages/session-projection/session-projection/tests/registry.spec.ts

@@ -169,6 +169,154 @@ describe('SessionProjectionRegistry drive', () => {
     expect(ctx.sessionProjections.snapshot(session).values).toEqual({})
   })
 
+  it('checkpoints every registered unit with its stateVersion and per-cell watermark', async () => {
+    const { ctx, session } = await harness()
+    ctx.sessionProjections.register(marksUnit())
+    ctx.sessionProjections.register({ ...countUnit(), stateVersion: 7 })
+    const markEvent = mark(session, ['a'])
+    const rows = ctx.sessionProjections.checkpoint(session)
+    expect(rows['test/marks']).toEqual({ ver: 1, seq: markEvent.seq, val: { marks: ['a'] } })
+    expect(rows['test/count']).toEqual({ ver: 7, seq: markEvent.seq, val: 1 })
+    // Empty log: init-derived state at watermark -1.
+    const fresh = ctx.sessions.create()
+    expect(ctx.sessionProjections.checkpoint(fresh)['test/marks']).toEqual({ ver: 1, seq: -1, val: null })
+  })
+
+  it('checkpoint states are detached clones — mutating them cannot corrupt the watermark cache', async () => {
+    const { ctx, session } = await harness()
+    ctx.sessionProjections.register(marksUnit())
+    mark(session, ['a'])
+    const rows = ctx.sessionProjections.checkpoint(session)
+    // Hostile (or merely careless) consumer mutates the handed-out state.
+    ;(rows['test/marks']?.val as { marks: string[] }).marks.push('INJECTED')
+    // The registry's authoritative cell is untouched: snapshot and a fresh
+    // checkpoint both still serve the committed value.
+    expect(ctx.sessionProjections.snapshot(session).values['test/marks']).toEqual({ marks: ['a'] })
+    expect(ctx.sessionProjections.checkpoint(session)['test/marks']?.val).toEqual({ marks: ['a'] })
+  })
+
+  it('restoreFloor anchors one below the lowest usable watermark and at 0 for missing or mismatched rows', async () => {
+    const { ctx } = await harness()
+    expect(ctx.sessionProjections.restoreFloor({})).toBeUndefined() // no unit registered
+    ctx.sessionProjections.register(marksUnit())
+    ctx.sessionProjections.register(countUnit())
+    expect(ctx.sessionProjections.restoreFloor({})).toBe(0)
+    // Lowest usable watermark is count's 5 → the anchored tail starts AT 5
+    // (one below the first needed seq 6), so the read proves seq 5 still exists.
+    expect(ctx.sessionProjections.restoreFloor({
+      'test/marks': { ver: 1, seq: 10, val: { marks: [] } },
+      'test/count': { ver: 1, seq: 5, val: 6 },
+    })).toBe(5)
+    // A version-mismatched row forces that key back to a full refold.
+    expect(ctx.sessionProjections.restoreFloor({
+      'test/marks': { ver: 2, seq: 10, val: { marks: [] } },
+      'test/count': { ver: 1, seq: 5, val: 6 },
+    })).toBe(0)
+    // A fresh (-1) row still needs the whole tail from 0.
+    expect(ctx.sessionProjections.restoreFloor({
+      'test/marks': { ver: 1, seq: -1, val: null },
+      'test/count': { ver: 1, seq: -1, val: 0 },
+    })).toBe(0)
+  })
+
+  it('restore folds the tail past each usable row and refolds from init on version mismatch', async () => {
+    const { ctx } = await harness()
+    ctx.sessionProjections.register(marksUnit())
+    ctx.sessionProjections.register(countUnit())
+    const tail: SessionEvent[] = [
+      { type: 'test/mark', seq: 3, time: 3, data: { marks: ['new'] } },
+      { type: 'turn/end', seq: 4, time: 4, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    // marks row usable (watermark 2, tail starts at 3); count row mismatched — but
+    // a mismatch with baseSeq > 0 cannot silently refold: it throws for a re-read.
+    expect(() => ctx.sessionProjections.restore({
+      'test/marks': { ver: 1, seq: 2, val: { marks: ['old'] } },
+      'test/count': { ver: 99, seq: 2, val: 3 },
+    }, tail, 3)).toThrow(/re-read from seq 0/)
+    // The full-log re-read (baseSeq 0) refolds the mismatched key from init.
+    const full: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'test/mark', seq: 1, time: 1, data: { marks: ['old'] } },
+      { type: 'test/mark', seq: 2, time: 2, data: { marks: ['old', '2'] } },
+      ...tail,
+    ]
+    const { snapshot, checkpoint } = ctx.sessionProjections.restore({
+      'test/marks': { ver: 1, seq: 2, val: { marks: ['old', '2'] } },
+      'test/count': { ver: 99, seq: 2, val: 3 },
+    }, full, 0)
+    expect(snapshot.asOfSeq).toBe(4)
+    expect(snapshot.values['test/marks']).toEqual({ marks: ['new'] })
+    expect(snapshot.values['test/count']).toBe(5) // refolded from init over all 5 events
+    // The refreshed rows sit at the served cut, ready for a durable write-back.
+    expect(checkpoint['test/marks']).toEqual({ ver: 1, seq: 4, val: { marks: ['new'] } })
+    expect(checkpoint['test/count']).toEqual({ ver: 1, seq: 4, val: 5 })
+  })
+
+  it('restore over a suffix folds only past each row watermark and serves an exact empty-tail cut', async () => {
+    const { ctx } = await harness()
+    ctx.sessionProjections.register(marksUnit())
+    ctx.sessionProjections.register(countUnit())
+    const rows = {
+      'test/marks': { ver: 1, seq: 4, val: { marks: ['done'] } },
+      'test/count': { ver: 1, seq: 2, val: 3 },
+    }
+    const tail: SessionEvent[] = [
+      { type: 'turn/start', seq: 3, time: 3, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'turn/end', seq: 4, time: 4, data: { turn: 2, reason: { kind: 'completed' } } },
+    ]
+    const { snapshot } = ctx.sessionProjections.restore(rows, tail, 3)
+    expect(snapshot.asOfSeq).toBe(4)
+    // marks already covers the tail (watermark 4): nothing re-applied.
+    expect(snapshot.values['test/marks']).toEqual({ marks: ['done'] })
+    // count folds exactly seqs 3 and 4 on top of its checkpoint.
+    expect(snapshot.values['test/count']).toBe(5)
+
+    // Empty tail (checkpoint is current): the cut sits at baseSeq - 1.
+    const { snapshot: current } = ctx.sessionProjections.restore({
+      'test/marks': { ver: 1, seq: 4, val: { marks: ['done'] } },
+      'test/count': { ver: 1, seq: 4, val: 5 },
+    }, [], 5)
+    expect(current.asOfSeq).toBe(4)
+    expect(current.values['test/count']).toBe(5)
+  })
+
+  it('viewCheckpoint serves version-matching rows without any log and skips mismatched keys', async () => {
+    const { ctx } = await harness()
+    ctx.sessionProjections.register(marksUnit())
+    ctx.sessionProjections.register(countUnit())
+    const values = ctx.sessionProjections.viewCheckpoint({
+      'test/marks': { ver: 1, seq: 4, val: { marks: ['stored'] } },
+      'test/count': { ver: 99, seq: 4, val: 5 }, // mismatched: absent
+    })
+    expect(values['test/marks']).toEqual({ marks: ['stored'] })
+    expect('test/count' in values).toBe(false)
+    expect(ctx.sessionProjections.viewCheckpoint({})).toEqual({})
+  })
+
+  it('restore rejects a row claiming events past the supplied log end (shrunk log ⇒ re-read)', async () => {
+    const { ctx } = await harness()
+    ctx.sessionProjections.register(countUnit())
+    const rows = { 'test/count': { ver: 1, seq: 9, val: 10 } }
+    // The anchored floor sits ON the watermark, so the tail read must return
+    // at least seq 9 from an intact log…
+    const floor = ctx.sessionProjections.restoreFloor(rows)
+    expect(floor).toBe(9)
+    // …an intact log serves the anchor event and the checkpoint stands as-is.
+    const anchor: SessionEvent = { type: 'turn/end', seq: 9, time: 9, data: { turn: 2, reason: { kind: 'completed' } } }
+    expect(ctx.sessionProjections.restore(rows, [anchor], 9).snapshot.values['test/count']).toBe(10)
+    // …while a log crash-repaired down to fewer events returns an empty tail:
+    // the row overreaches the proven end and a tail read cannot fix this key.
+    expect(() => ctx.sessionProjections.restore(rows, [], 9)).toThrow(/re-read from seq 0/)
+    // The full re-read discards the overreaching row and refolds from init.
+    const events: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'turn/end', seq: 1, time: 1, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    const { snapshot } = ctx.sessionProjections.restore(rows, events, 0)
+    expect(snapshot.asOfSeq).toBe(1)
+    expect(snapshot.values['test/count']).toBe(2)
+  })
+
   it('fails loud when a unit view violates its own schema (async unit output is unrepresentable)', async () => {
     const { ctx, session } = await harness()
     ctx.sessionProjections.register({

packages/session-query/session-query-sqlite/src/schema.ts

@@ -5,7 +5,7 @@ import { mkdir, open } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 
 /** Current derived-index schema version. Incompatible versions reset in place. */
-export const SESSION_QUERY_SQLITE_SCHEMA_VERSION = 5
+export const SESSION_QUERY_SQLITE_SCHEMA_VERSION = 7
 
 /** SQLite application id protecting unrelated databases from derived resets. */
 export const SESSION_QUERY_SQLITE_APPLICATION_ID = 0x44534851

packages/session-query/session-query-sqlite/tests/sqlite.spec.ts

@@ -149,6 +149,11 @@ class TestPersistence extends SessionPersistence {
     return structuredClone(entry)
   }
 
+  async readFrom(id: SessionIdType, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    const whole = await this.inspect(id, signal)
+    return { meta: whole.meta, events: whole.events.filter(event => event.seq >= fromSeq) }
+  }
+
   async list(): Promise<SessionHeader[]> {
     TestPersistence.listStarted?.()
     await TestPersistence.listGate

packages/session-query/session-query/tests/session-query.spec.ts

@@ -96,6 +96,11 @@ class TestPersistence extends SessionPersistence {
     return Promise.resolve(result)
   }
 
+  async readFrom(id: SessionIdType, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    const whole = await this.inspect(id, signal)
+    return { meta: whole.meta, events: whole.events.filter(event => event.seq >= fromSeq) }
+  }
+
   list(signal?: AbortSignal): Promise<SessionHeader[]> {
     TestPersistence.listCalls += 1
     TestPersistence.listSignals.push(signal)

packages/session-query/session-query/tests/tracing.spec.ts

@@ -76,6 +76,11 @@ class TracePersistence extends SessionPersistence {
     return Promise.resolve(structuredClone(entry))
   }
 
+  async readFrom(id: SessionIdType, fromSeq: number): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    const whole = await this.inspect(id)
+    return { meta: whole.meta, events: whole.events.filter(event => event.seq >= fromSeq) }
+  }
+
   list(): Promise<SessionHeader[]> {
     TracePersistence.listCalls += 1
     if (TracePersistence.listFailure !== undefined) return Promise.reject(TracePersistence.listFailure)

packages/subagent/subagent-inprocess/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent-inprocess/README.md
-README.md: 3606799e6d16e80473006f82b834a10953270914
-README.zh.md: 7f52d3699d1240f960e437d12bc48a152658cd15
+README.md: 980bc18de088c41dfe2f57a5ff0882a60892fc9f
+README.zh.md: 1ceb628371c3ae9cee6d8afa6bc1d95ba4cda8ae