Merge remote-tracking branch 'origin/master' into feat/send-unify

# Conflicts:
#	docs/persistence-catalog.md
#	examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	packages/context/time-context/tests/time-context.spec.ts
#	packages/cordis/tool-cordis/src/api-catalog.ts

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

@@ -34,9 +34,12 @@ export type {
 } from './contract/store.ts'
 export type {
   AssistantBlock, AssistantMessageNode, ContextMessageNode, ConversationNode, ConversationSnapshot,
-  PendingInteraction, RunningToolCall, SteeringMessageNode,
+  RunningToolCall, SteeringMessageNode,
   ToolResultNode, UnknownSurfaceNode, UserMessageNode,
 } from './sessions/conversation.ts'
+// PendingWait is a value export: tests construct fixture waits directly.
+export { PendingWait } from './sessions/pending.ts'
+export type { PendingInteraction, PendingKind, PendingPayloads } from './sessions/pending.ts'
 export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 
 // ---- Narrowed aliases (the single narrowing point of the slot type chain:
@@ -51,7 +54,7 @@ export type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
  */
 export type ClientContext = Context
 
-/** The conversation-snapshot selector hook (ConvViewProps/ToolViewProps take this). */
+/** The conversation-snapshot selector hook (ConvViewProps/ToolRowProps take this). */
 export type UseConversationSession = SnapshotSelectorHook<ConversationSnapshot>
 
 /**

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

@@ -4,7 +4,8 @@
 // string here (narrow to real brands when convenient).
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
-import type { RpcError, RpcId, SessionId, ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { RpcError, SessionId, ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { PendingInteraction } from './pending.ts'
 
 /** Assistant content blocks sorted by what the UI cares about
  *  (text body / collapsible reasoning / tool-call card head / other fallback). */
@@ -121,11 +122,6 @@ export interface RunningToolCall {
   callView: ToolCallView | null
 }
 
-/** Approval/question placeholder cards (visible, not answerable;
- *  rpcId = the requested frame's envelope id, the future respond backfill key). */
-export type PendingInteraction =
-  | { kind: 'approval'; rpcId: RpcId; approvalId: string; toolName: string; callId?: string; reason?: string }
-  | { kind: 'question'; rpcId: RpcId; questions: readonly unknown[] }
 
 /** In-progress assistant output (chunk accumulator product). */
 export interface PartialAssistant {

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

@@ -0,0 +1,79 @@
+// PendingWait: the carrier-protocol half of a pending host interaction. The runtime owns only
+// envelope knowledge (rpcId backfill into a client-response); domain result encoding belongs to
+// the interaction's consumer package.
+
+import type {
+  ClientResponse, MuxFrame, RpcId, RpcReceipt, SessionId,
+} from '@deepseek-ai/dsh-client-connection/client'
+
+/** Kind-keyed payload map: the requested frame's domain fields (envelope fields stripped). */
+export interface PendingPayloads {
+  approval: Omit<Extract<MuxFrame, { type: 'approval/requested' }>, 'type' | 'sessionId'>
+  question: Omit<Extract<MuxFrame, { type: 'question/requested' }>, 'type' | 'sessionId'>
+}
+
+/** Pending-interaction discriminant (the keys of PendingPayloads). */
+export type PendingKind = keyof PendingPayloads
+
+/** Kind-discriminated union of concrete waits: narrowing on `kind` types `payload`. */
+export type PendingInteraction = { [K in PendingKind]: PendingWait<K> }[PendingKind]
+
+/** Key prefixes, one per kind (the key doubles as the Session pending-map key). */
+const KEY_PREFIX: Record<PendingKind, string> = { approval: 'a', question: 'q' }
+
+/**
+ * One pending host-owned interaction wait: an immutable render face
+ * (kind/key/sessionId/payload) plus the response carrier. respond() backfills
+ * the requested frame's rpcId into a client-response envelope — no consumer
+ * ever sees the raw rpcId. Settlement is expressed only by pending-list
+ * membership (the settled flag is a fail-loud guard, not a render input).
+ */
+export class PendingWait<K extends PendingKind = PendingKind> {
+  /** Interaction kind (union discriminant). */
+  readonly kind: K
+  /** Opaque render identity, `<prefix>:<rpcId>` — stable across baseline replay, usable as a React key. */
+  readonly key: string
+  /** Owning session. */
+  readonly sessionId: SessionId
+  /** The requested frame's domain fields, verbatim. */
+  readonly payload: PendingPayloads[K]
+  #settled = false
+  readonly #rpcId: RpcId
+  readonly #respond: (message: ClientResponse) => Promise<RpcReceipt>
+
+  /**
+   * Minted by Session on a requested frame (public construction is the test-fixture path).
+   * @param kind - interaction kind.
+   * @param rpcId - the requested frame's stable envelope id (kept private; respond echoes it).
+   * @param sessionId - owning session.
+   * @param payload - the requested frame's domain fields.
+   * @param respond - the client-response carrier (api.respond).
+   */
+  constructor(
+    kind: K, rpcId: RpcId, sessionId: SessionId, payload: PendingPayloads[K],
+    respond: (message: ClientResponse) => Promise<RpcReceipt>,
+  ) {
+    this.kind = kind
+    this.key = `${KEY_PREFIX[kind]}:${rpcId}`
+    this.sessionId = sessionId
+    this.payload = payload
+    this.#rpcId = rpcId
+    this.#respond = respond
+  }
+
+  /**
+   * Send a result for this wait: wraps it into the client-response envelope
+   * with the rpcId backfilled. Throws synchronously once settled.
+   * @param result - the result shell (ok value / error envelope), domain-encoded by the caller.
+   * @returns the carrier receipt.
+   */
+  respond(result: ClientResponse['result']): Promise<RpcReceipt> {
+    if (this.#settled) throw new Error(`pending wait ${this.key} is already settled`)
+    return this.#respond({ type: 'client-response', rpcId: this.#rpcId, result })
+  }
+
+  /** Session-only settlement mark (the authoritative resolved frame arrived); respond() throws afterwards. */
+  markSettled(): void {
+    this.#settled = true
+  }
+}

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

@@ -5,13 +5,14 @@
  * slot-parity design), session scope tree (mintScope pattern: no-op plugin
  * Fiber + ctx.extend scope tag), stable SessionBinding cache, ancestry walk.
  *
- * Scope lifecycle is watch-driven: a scope is minted lazily on first
- * resolution; a session leaving the list tears its scope down only when
- * nobody is watching it. "Watched" is approximated as the most recently
- * resolved binding id — SessionProvider re-resolves on every selection
- * change (keyed remount), so a switch away always re-evaluates the deferred
- * teardown; a host-side death without list removal keeps the scope (frozen
- * read-only view).
+ * Scope lifecycle is stage-driven: a scope is minted lazily on first
+ * resolution (pure — resolution has no side effects and is render-safe);
+ * the event window and deferred teardown key off the STAGED session, which
+ * follows `list.current` exactly. Staging is the open signal: the window
+ * opens ⟺ the session is on stage (today the stage is `current`; the staged
+ * state can widen to a multi-pane list later). A session leaving the list
+ * tears its scope down immediately unless it is the staged one, whose scope
+ * survives frozen (read-only view) until the stage moves on.
  */
 import type { Context, Fiber } from 'cordis'
 import type { IApiClient, SessionId } from '@deepseek-ai/dsh-client-connection/client'
@@ -97,9 +98,14 @@ export class SessionsService {
   private readonly selection: SnapshotStore<{ sessionId?: SessionId }>
 
   private readonly scopes = new Map<SessionId, ScopeRecord>()
-  /** Most recently resolved binding id — the watch approximation for deferred teardown. */
+  /**
+   * The staged session id — follows `list.current` exactly, holding its last
+   * defined value across masked gaps (a transiently absent selection blanks
+   * `current` without moving the stage, so reconnect re-pulls and removals
+   * keep the staged scope's frozen view alive until the stage moves on).
+   */
   private watched: SessionId | undefined
-  /** Removed-while-watched sessions whose teardown waits for the watch to move away. */
+  /** Removed-while-staged sessions whose teardown waits for the stage to move away. */
   private readonly deferredRemovals = new Set<SessionId>()
 
   /**
@@ -115,6 +121,13 @@ export class SessionsService {
     // The manager owns wire truth; the store is its projection. Manager
     // notifications are already microtask-batched.
     this.manager.subscribe(() => { this.projectList() })
+    // Stage follower: every current write (open() and projection alike)
+    // re-evaluates staging, so startup restore (persisted selection validated
+    // by the projection) and reconnect resurfacing open their window with no
+    // dedicated code path. Safe to run synchronously inside the store notify:
+    // the follower writes no list state — session.open()'s synchronous prefix
+    // touches only session-side state and its own microtask-batched notifier.
+    this.list.subscribe(() => { this.followCurrent() })
     rootCtx.reflect.provide('sessions', this, undefined)
   }
 
@@ -152,35 +165,50 @@ export class SessionsService {
   }
 
   /**
-   * Resolve the stable session binding (SessionProvider's resolveBinding feed).
+   * Resolve the stable session binding (scope-addressed assembly feed). Pure
+   * resolution — no staging, no window side effects.
    * @param id - session id.
    * @returns binding, or undefined for a session neither listed nor already scoped.
    */
   binding(id: SessionId): SessionBinding | undefined {
-    const record = this.resolve(id)
-    if (record === undefined) return undefined
-    if (this.watched !== id) {
-      this.watched = id
-      this.sweepDeferred()
-    }
-    return record.binding
+    return this.resolve(id)?.binding
   }
 
   /**
    * Resolve the render-layer session cell (SessionProvider's feed through
-   * the renderer host; ctx never enters the render layer). Marks the session
-   * watched, same as {@link SessionsService.binding}.
+   * the renderer host; ctx never enters the render layer). Pure resolution —
+   * render-safe: SessionProvider calls this during render, so no staging, no
+   * window side effects (StrictMode double-invokes and concurrent discarded
+   * passes must stay free).
    * @param id - session id.
    * @returns cell, or undefined for a session neither listed nor already scoped.
    */
   cell(id: string): SessionCell | undefined {
-    const record = this.resolve(id as SessionId)
-    if (record === undefined) return undefined
-    if (this.watched !== id) {
-      this.watched = id as SessionId
-      this.sweepDeferred()
+    return this.resolve(id as SessionId)?.cell
+  }
+
+  /**
+   * Move the stage to the list's current session: sweep teardowns deferred
+   * behind the previous occupant and pull the new occupant's history window.
+   * Staging IS the open signal — the window opens ⟺ the session is on stage
+   * — and open() is idempotent (an in-flight or completed open no-ops; a
+   * failed one retries the next time current is touched).
+   */
+  private followCurrent(): void {
+    const current = this.list.getSnapshot().current
+    // A masked gap (current blanked while the selection's session is
+    // transiently absent) holds the stage: tearing down on the gap would
+    // destroy exactly the frozen scope the mask exists to preserve.
+    if (current === undefined || current === this.watched) return
+    this.watched = current
+    this.sweepDeferred()
+    const record = this.resolve(current)
+    /* v8 ignore next 3 -- defensive: current is always a listed id (open()
+     * 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()
     }
-    return record.cell
   }
 
   /**
@@ -246,7 +274,7 @@ export class SessionsService {
     this.pruneScopes(byId)
   }
 
-  /** Tear down scopes for removed sessions nobody watches; the watched one defers until the watch moves. */
+  /** Tear down scopes for removed sessions off stage; the staged one defers until the stage moves. */
   private pruneScopes(byId: Record<SessionId, SessionSummary>): void {
     for (const [id, record] of this.scopes) {
       if (byId[id] !== undefined) continue
@@ -268,11 +296,11 @@ export class SessionsService {
     this.rootCtx.get('slots')?.pruneStoreScope(id)
   }
 
-  /** Run deferred teardowns whose session is no longer watched (called when the watch moves). */
+  /** Run deferred teardowns whose session is no longer staged (called when the stage moves). */
   private sweepDeferred(): void {
     for (const id of [...this.deferredRemovals]) {
-      /* v8 ignore next -- defensive: only the watched id ever defers, and every
-       * watch move sweeps first, so the set cannot contain the id the watch just
+      /* v8 ignore next -- defensive: only the staged id ever defers, and every
+       * stage move sweeps first, so the set cannot contain the id the stage just
        * moved to; kept as a guard against future extra sweep call sites. */
       if (id === this.watched) continue
       // Still absent from the list? (A re-added id cancels the deferred teardown.)

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

@@ -5,12 +5,17 @@
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
-import type { HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult, SessionId, ToolEventView } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  HistoryEntry, IApiClient, MuxFrame, RpcError, RpcId, RpcResult,
+  SessionId, ToolEventView,
+} from '@deepseek-ai/dsh-client-connection/client'
 import { transportError } from '@deepseek-ai/dsh-client-connection/client'
 import type { ObservableSnapshot } from '../contract/store.ts'
 import type {
-  ConversationNode, ConversationSnapshot, OpenState, PendingInteraction, PromptError, RunningToolCall,
+  ConversationNode, ConversationSnapshot, OpenState, PromptError, RunningToolCall,
 } from './conversation.ts'
+import type { PendingInteraction } from './pending.ts'
+import { PendingWait } from './pending.ts'
 import { FoldAdapter } from './fold-adapter.ts'
 import { Notifier } from './notifier.ts'
 import { PartialAccumulator } from './partial.ts'
@@ -183,7 +188,9 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
     this.events = []
     this.views = []
     this.baseSeq = 0
-    this.pending.clear() // the subscribed baseline replay re-sends still-pending requested frames verbatim
+    // Superseded, not settled: the baseline replay re-sends still-pending requested frames verbatim
+    // (same rpcId), re-minting fresh waits; a stale reference's respond() still reaches the host.
+    this.pending.clear()
     this.pendingRev++
     this.subscribedLastSeq = null
     this.liveBuffer = []
@@ -229,33 +236,27 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
         return // pure baseline bookkeeping, no visible change
       }
       case 'approval/requested': {
-        this.pending.set(`a:${rpcId}`, {
-          kind: 'approval', rpcId, approvalId: frame.approvalId, toolName: frame.toolName,
-          ...(frame.callId !== undefined ? { callId: frame.callId } : {}),
-          ...(frame.reason !== undefined ? { reason: frame.reason } : {}),
-        })
-        this.pendingRev++
+        const { type: _type, sessionId: _sid, ...payload } = frame
+        this.mint(new PendingWait('approval', rpcId, this.sessionId, payload, m => this.api.respond(m)))
         this.notifier.markDirty()
         return
       }
       case 'approval/resolved': {
-        for (const [key, item] of this.pending) {
-          if (item.kind === 'approval' && item.approvalId === frame.approvalId) {
-            this.pending.delete(key)
-            this.pendingRev++
-          }
+        for (const item of this.pending.values()) {
+          if (item.kind === 'approval' && item.payload.approvalId === frame.approvalId) this.settle(item)
         }
         this.notifier.markDirty()
         return
       }
       case 'question/requested': {
-        this.pending.set(`q:${rpcId}`, { kind: 'question', rpcId, questions: frame.questions })
-        this.pendingRev++
+        const { type: _type, sessionId: _sid, ...payload } = frame
+        this.mint(new PendingWait('question', rpcId, this.sessionId, payload, m => this.api.respond(m)))
         this.notifier.markDirty()
         return
       }
       case 'question/resolved': {
-        if (this.pending.delete(`q:${frame.questionRpcId}`)) this.pendingRev++
+        const item = this.pending.get(`q:${frame.questionRpcId}`)
+        if (item !== undefined) this.settle(item)
         this.notifier.markDirty()
         return
       }
@@ -295,6 +296,19 @@ export class Session implements ObservableSnapshot<ConversationSnapshot> {
 
   // ---- 私有 ----
 
+  /** Requested-frame arrival: the wait enters the pending map under its own key. */
+  private mint(wait: PendingInteraction): void {
+    this.pending.set(wait.key, wait)
+    this.pendingRev++
+  }
+
+  /** Authoritative resolved-frame settlement: mark, then drop from the pending map. */
+  private settle(wait: PendingInteraction): void {
+    wait.markSettled()
+    this.pending.delete(wait.key)
+    this.pendingRev++
+  }
+
   /** @param generation - openGeneration at launch; every await re-checks it and a stale pass
    *  drops all writes (resync superseded this open — its outcome belongs to a dead connection). */
   private async doOpen(generation: number): Promise<void> {

packages/client/runtime/src/client/slots.ts

@@ -66,6 +66,10 @@ interface ErasedRegisterOptions {
   id?: string
   order?: number
   label?: string
+  /** Chain-slot routing selector (pure; the core validates presence for chain targets). */
+  select?: (owner: never) => unknown
+  /** Chain-slot explicit ordering override (ascending; registration order otherwise). */
+  priority?: number
   registrant?: string
 }