dsh-zen-remote 2.3.10 → 2.4.0

package/src/intercept.ts

@@ -81,20 +81,23 @@
 
 import { RelayError, defaultClock } from './relay-client.js'
 import type { RelayClient, RelayClock, RelayState } from './relay-client.js'
+import type { RelayPool } from './relay-pool.js'
 import { checkGatewayShape } from './intercept-shape.js'
 import type { GatewayShapeCheck } from './intercept-shape.js'
 import { fromVirtual, isVirtual, toVirtual } from './virtual-id.js'
 import { INVOKE_BINARY_RESULT_METHODS, extractResultAttachments, restoreInvokeBinary, type ResultAttachment } from './invoke-binary.js'
 import {
+  composeMergedWorkspaceFrames,
   createControlMerger,
   createWorkspaceMerger,
+  localWorkspaceLists,
   mergeModelCatalogs,
   mergeSessionList,
   sessionSummaryAddedFrames,
   virtualSessionIdsInWorkspaceFrames,
   virtualizeModelSelectionValue,
 } from './merge-streams.js'
-import type { ControlMerger, MergerAnnotation, MergerIdentity, WorkspaceMerger } from './merge-streams.js'
+import type { ControlMerger, MergerAnnotation, MergerIdentity, MergerLang, RemoteWorkspaceContribution, WorkspaceMerger } from './merge-streams.js'
 
 /** The session-locating argument fields, as registered per method. Identical
  * in name and meaning to relay-access.ts's `SessionField`; a field named
@@ -203,6 +206,11 @@ export const CLIENT_METHOD_FIELDS: Readonly<Record<string, readonly SessionField
   'terminal/rename': ['agentId'],
   'terminal/close': ['agentId'],
   'terminal/follow': ['agentId'],
+  // TA-1: the 0.2.2 duplex stream (follow+write+resize merged), located by
+  // the same agentId. TA-2 wired the interceptor half: the host's uplink
+  // inbox and its window travel to the relay's openStream options (see
+  // REMOTE_UPLINK_STREAM_METHODS) instead of being half-closed.
+  'terminal/attach': ['agentId'],
   // the retain/list half locates by a plain top-level json sessionId
   'terminal/list': ['sessionId'],
   'terminal/retain': ['sessionId'],
@@ -344,12 +352,54 @@ export function isRemoteWrite(endpoint: string): boolean {
   return !REMOTE_READ_METHODS.has(endpoint)
 }
 
-/** The refusal a write gets while the relay is not serving (T34). */
-const WRITE_OFFLINE_MESSAGE = '服务端离线，远程会话暂时只读'
+/**
+ * Stream endpoints whose caller-supplied `uplink` iterable and
+ * `uplinkWindow` travel to the relay instead of being half-closed locally
+ * with `releaseUplink`. DSH 0.2.2+ replaced `terminal/follow|write|resize`
+ * with the duplex `terminal/attach` stream (`TerminalInput` write/resize
+ * commands ride the uplink; `ack` frames ride the downlink). The relay
+ * client's pump (relay-client.ts) is the other half: it forwards the host's
+ * frames through the server's `/v1/stream-uplink` channel and releases the
+ * host inbox itself when the stream ends — the interceptor only hands the
+ * iterable over, it never half-closes a member of this set.
+ */
+export const REMOTE_UPLINK_STREAM_METHODS: ReadonlySet<string> = new Set(['terminal/attach'])
+
+export type InterceptLang = MergerLang
+
+const INTERCEPT_COPY = {
+  zh: {
+    writeOffline: '服务端离线，远程会话暂时只读',
+    closed: '远程已关闭',
+    notConnected: '尚未连接到服务端',
+    mismatch: '此远程会话属于其他主服务端',
+    unsupported: '此功能暂不支持远程会话',
+    referenceNotOnServer: '引用的会话不在服务端上，无法转发',
+    revoked: '配对令牌已被吊销，请在设置页重新配对',
+    unpaired: '尚未与服务端配对，请在设置页完成配对',
+    modelGroupRemote: '该模型分组属于远程服务端，无法在本机会话中使用',
+    modelGroupPickServer: (displayName: string) => `请选择「${displayName} · …」分组里的模型`,
+    modelGroupMismatch: '此模型分组属于其他主服务端',
+  },
+  en: {
+    writeOffline: 'Server offline — remote session is temporarily read-only',
+    closed: 'Remote closed',
+    notConnected: 'Not connected to the server yet',
+    mismatch: 'This remote session belongs to another server',
+    unsupported: 'This feature is not supported in remote sessions yet',
+    referenceNotOnServer: 'Referenced session is not on the server and cannot be forwarded',
+    revoked: 'Pairing token was revoked — please pair again in Settings',
+    unpaired: 'Not paired with the server yet — please pair in Settings',
+    modelGroupRemote: 'This model group belongs to a remote server and cannot be used in a local session',
+    modelGroupPickServer: (displayName: string) => `Select a model under "${displayName} · …"`,
+    modelGroupMismatch: 'This model group belongs to another server',
+  },
+} as const
 
-/** What a call or stream on a closed remote session answers in place of the
- * relay's own text (T73) — the banner already says why. */
-const CLOSED_MESSAGE = '远程已关闭'
+function resolveInterceptLang(lang: InterceptLang | (() => InterceptLang) | undefined): InterceptLang {
+  const value = typeof lang === 'function' ? lang() : lang
+  return value === 'en' ? 'en' : 'zh'
+}
 
 /**
  * The RelayError codes that mean "the LINK went down under a live stream"
@@ -518,6 +568,26 @@ function releaseUplink(uplink: unknown): void {
   }
 }
 
+/**
+ * The shape check one duplex stream's `uplinkWindow` must pass before it
+ * travels (TA-2) — the same rule the server re-applies on `/v1/stream`
+ * (relay-server.ts): positive safe-integer `maxBytes`, non-negative
+ * safe-integer `frameOverheadBytes`. Anything else — an older host's
+ * `undefined`, a non-object, a fractional or negative budget — comes back
+ * `undefined` and the stream forwards with the relay's own default window:
+ * the numbers are the host's contract with itself, garbage is dropped, never
+ * refused.
+ */
+function normalizeUplinkWindow(raw: unknown): { maxBytes: number; frameOverheadBytes: number } | undefined {
+  if (!isPlainObject(raw)) return undefined
+  const { maxBytes, frameOverheadBytes } = raw
+  if (typeof maxBytes !== 'number' || !Number.isSafeInteger(maxBytes) || maxBytes <= 0) return undefined
+  if (typeof frameOverheadBytes !== 'number' || !Number.isSafeInteger(frameOverheadBytes) || frameOverheadBytes < 0) {
+    return undefined
+  }
+  return { maxBytes, frameOverheadBytes }
+}
+
 /** One remote-call failure in the diagnostics ring. */
 export interface InterceptFailureRecord {
   /** ISO timestamp of the moment the failure was recorded. */
@@ -622,12 +692,21 @@ export interface InstallInterceptOptions {
   /** The RAW gateway instance (`ctx.typertGateway[symbols.original]`), not
    * the cordis proxy — own properties on the proxy are ignored by everyone. */
   raw: object
-  /** The client relay client (T23a) the calls travel through. */
-  relay: RelayClient
-  /** The CURRENT handshake's server id, read live per call; `undefined`
-   * (never handshook) makes every remote call a `remote-offline` — a
-   * different fact from pointing at the wrong server (`remote-mismatch`). */
-  getServerId: () => string | undefined
+  /** SINGLE-SERVER mode (the original wiring, kept for compatibility): the
+   * one client relay client the calls travel through. Either this + 
+   * {@link getServerId}, or {@link pool} — never required together. */
+  relay?: RelayClient
+  /** SINGLE-SERVER mode: the CURRENT handshake's server id, read live per
+   * call; `undefined` (never handshook) makes every remote call a
+   * `remote-offline` — a different fact from pointing at the wrong server
+   * (`remote-mismatch`). */
+  getServerId?: () => string | undefined
+  /** MS-3 POOL mode: the multi-server relay pool (up to
+   * `MAX_PAIRED_SERVERS` paired servers). When present it replaces the
+   * single-relay routing: every call/stream/event routes by the virtual
+   * id's `serverId` to the matching pool entry, and the three global reads
+   * plus the model catalog merge ALL paired servers in pairing order. */
+  pool?: RelayPool
   /** Progress logging, wired to the context logger by index.ts. */
   log?: (format: string, ...args: unknown[]) => void
   /** Clock/timers for the merged streams' reopen backoff (CP4); defaults to
@@ -645,10 +724,15 @@ export interface InstallInterceptOptions {
   /** PB-25b: the inventory slot factory — one slot per merged global stream
    * (only the workspace merger ever reports; the control merger has no
    * session inventory). The wiring unions the live slots' shares into the
-   * set the plugin-route rewrite reads. Absent: no shares are ever reported
-   * and the plugin-route value scan stays exactly the request-local
-   * behavior. */
-  createSessionInventorySlot?: () => SessionInventorySlot
+   * set the plugin-route rewrite consults. MS-3: the factory receives the
+   * slot's `serverId`, so a pool wiring can keep per-server inventories
+   * (the plain single-server wiring can ignore the argument). Absent: no
+   * shares are ever reported and the plugin-route value scan stays exactly
+   * the request-local behavior. */
+  createSessionInventorySlot?: (serverId?: string) => SessionInventorySlot
+  /** Language for error messages and sidebar group suffixes (`'zh'` default,
+   * `'en'` English). Accepts a getter for live resolution. */
+  lang?: InterceptLang | (() => InterceptLang) | undefined
 }
 
 export interface InterceptHandle {
@@ -677,6 +761,20 @@ export interface InterceptHandle {
    * entries are dropped; a batch with nothing left is a no-op. Reaches every
    * live merged `$events` stream, and the pending slot when none is open. */
   nudgeSummarySync(ids: readonly string[]): void
+  /** MS-3 (pool mode only meaningful, harmless otherwise): the pool's entry
+   * set or any entry's identity moved — the wiring forwards the pool's
+   * `onServerRemoved` / `onStateChange` callbacks here. Every live merged
+   * stream re-scans `pool.entries()` NOW: slots for removed entries leave
+   * (only THAT server's shown groups and pending events are torn down),
+   * slots for new entries start, and renames re-title the groups. */
+  notePoolEvent(): void
+  /** P55-2: resolve which remote session (serverId + real sessionId) should
+   * serve a path-only `/api/file?path=...` request, or `undefined` when the
+   * local route should handle it. Read by the fetch-route wrap (its media
+   * mount only exists while the wiring hands THIS handle's method over), so
+   * a Markdown image of a remote session's reply loads from the server's
+   * disk instead of 404ing on the sub-client's own. */
+  resolveRemoteFileScope(path: string): { serverId: string; sessionId: string } | undefined
 }
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -1369,6 +1467,7 @@ interface MergedGlobalStreamDeps {
    * {@link SessionInventorySlot}). One slot per merged stream, disposed with
    * it; absent when the wiring passed no factory. */
   createSessionInventorySlot?: () => SessionInventorySlot
+  lang?: InterceptLang | (() => InterceptLang) | undefined
 }
 
 /**
@@ -1413,6 +1512,7 @@ async function* mergedGlobalStream(deps: MergedGlobalStreamDeps): AsyncGenerator
           serverName: initial?.serverName ?? '',
           onDiagnostic,
           now: clock.now,
+          lang: deps.lang,
           ...(sessionSlot !== undefined ? { onKnownSessions: (ids: ReadonlySet<string>) => sessionSlot.replace(ids) } : {}),
         })
 
@@ -1470,7 +1570,13 @@ async function* mergedGlobalStream(deps: MergedGlobalStreamDeps): AsyncGenerator
   // away, and a navigation writes no relay frames. An `unavailable` read is
   // skipped entirely: the merger falls back to the conservative tombstone
   // behavior then.
+  let lastLang: InterceptLang = resolveInterceptLang(deps.lang)
   const informCurrentSession = (): void => {
+    const nextLang = resolveInterceptLang(deps.lang)
+    if (nextLang !== lastLang) {
+      lastLang = nextLang
+      for (const frame of merger.onStatusChanged()) channel.push(frame)
+    }
     const read = deps.getCurrentSession()
     if (read.kind === 'unavailable') return
     for (const frame of merger.setCurrentSession(read.kind === 'open' ? read.sessionId : undefined)) channel.push(frame)
@@ -2495,241 +2601,1490 @@ async function* mergedEventsStream(deps: MergedEventsStreamDeps): AsyncGenerator
   }
 }
 
+// ---- MS-3: the pool-mode merged streams ------------------------------------
+//
+// The pool-mode counterparts of the two merged streams above. They keep the
+// SAME outer contract (the local stream is the base; a remote death emits
+// nothing; the hold/reopen discipline) but run ONE leg per pooled server:
+// every slot is keyed by its handshake `serverId`, the slot set is
+// re-scanned on every pool event and every slot's own state change, and the
+// canonical merged frames compose the slots' contributions in PAIRING order
+// (pool.entries() order — the connect order never reorders the sidebar).
+// A removed entry tears down only ITS slot: only that server's shown
+// workspace groups leave the sidebar and only that server's pending
+// approvals get the synthesized cancels.
+
+interface PoolGlobalSlot {
+  kind: 'workspace' | 'control'
+  serverId: string
+  entryId: string
+  client: RelayClient
+  merger: WorkspaceMerger | ControlMerger
+  /** The pool display name this slot's merger is currently titled with. */
+  viewName: string
+  controller: AbortController | undefined
+  offState: () => void
+  annotation: MergerAnnotation
+  reopenDelayMs: number
+  removed: boolean
+  /** PB-25b, pool form: one inventory slot per WORKSPACE server, disposed
+   * with the slot (the single-server stream's slot dies with the stream). */
+  inventory: SessionInventorySlot | undefined
+}
+
+interface MergedGlobalStreamMultiDeps {
+  endpoint: 'workspace/follow' | 'session/control'
+  namespace: string
+  method: string
+  local: AsyncIterable<unknown>
+  pool: RelayPool
+  signal: AbortSignal | undefined
+  recordFailure: (endpoint: string, code: string) => void
+  log: ((format: string, ...args: unknown[]) => void) | undefined
+  clock: RelayClock
+  getCurrentSession: () => CurrentSessionRead
+  watchCurrentSession(fn: () => void): () => void
+  watchUninstall(fn: () => void): () => void
+  summarySync: SessionSummarySync
+  createSessionInventorySlot?: (serverId?: string) => SessionInventorySlot
+  /** Subscribe to the wiring's pool-event broadcasts (handle.notePoolEvent).
+   * Every broadcast re-scans the slot set. */
+  watchPool(fn: () => void): () => void
+  lang?: InterceptLang | (() => InterceptLang) | undefined
+}
+
 /**
- * Install the two own-property wrappers on the raw gateway. Assumes
- * {@link checkGatewayShape} passed (the wiring gates on it) — this function
- * records the verdict but does not re-gate, so it stays usable in tests
- * that install over deliberately odd shapes.
+ * The pool-mode merged global stream. Per server slot the same rules as the
+ * single-server merged stream apply; the slots' outputs differ only in the
+ * GLOBAL frames (`order` / `archived` / `pinned` and the baseline's merged
+ * lists), which are never taken from a slot's own merger — they are
+ * composed canonically from every slot's contribution in pairing order
+ * (composeMergedWorkspaceFrames). Per-workspace frames (upserts and
+ * removes) are slot-local facts and pass as the merger produced them.
  */
-export function installIntercept(options: InstallInterceptOptions): InterceptHandle {
-  const { raw, relay, getServerId, log } = options
-  const clock = options.clock ?? defaultClock
-  // T63: the summary-sync hub shared by the merged streams — the workspace
-  // route nudges, the events leg fetches-and-announces. One per install: it
-  // outlives individual stream generations so a nudge from a workspace leg
-  // reaches whichever $events generation is open.
-  const summarySync = createSessionSummarySync()
-  // PB-25b: the inventory slot factory (the wiring's union feed) — passed
-  // down to every merged stream, which owns one slot for its lifetime.
-  const createSessionInventorySlot = options.createSessionInventorySlot
-  // T62: the current-session getter and the live-merged-stream listener
-  // registry behind handle.currentSessionChanged().
-  const getCurrentSession = options.getCurrentSession ?? (() => ({ kind: 'unavailable' }) as const)
-  const currentSessionListeners = new Set<() => void>()
-  const watchCurrentSession = (fn: () => void): (() => void) => {
-    currentSessionListeners.add(fn)
-    return () => { currentSessionListeners.delete(fn) }
+async function* mergedGlobalStreamMulti(deps: MergedGlobalStreamMultiDeps): AsyncGenerator<unknown, void, undefined> {
+  const { endpoint, namespace, method, local, pool, signal, recordFailure, log, clock } = deps
+  if (signal?.aborted === true) return
+  const isWorkspace = endpoint === 'workspace/follow'
+  const onDiagnostic = (message: string): void => {
+    log?.('client multi merge dropped a frame on %s: %s', endpoint, message)
   }
-  const uninstallListeners = new Set<() => void>()
-  const watchUninstall = (fn: () => void): (() => void) => {
-    uninstallListeners.add(fn)
-    return () => { uninstallListeners.delete(fn) }
+  const channel = createFrameChannel()
+  let alive = true
+  const slots = new Map<string, PoolGlobalSlot>()
+  const onlineWaiters: (() => void)[] = []
+  const flushWaiters = (): void => {
+    for (const wake of onlineWaiters.splice(0)) wake()
   }
-  const gateway = raw as Record<string | symbol, unknown>
-  const shape = checkGatewayShape(raw)
-  const counters = { openWireStream: 0, dispatchRpc: 0 }
-  const failures: InterceptFailureRecord[] = []
-  const incompatible: IncompatibleCallRecord[] = []
-  // The closed-session registry (T34): insertion-ordered, capped, virtual-id
-  // keyed. Entries live until THEIR session proves reachable again (a
-  // succeeding call for it) — a reconnect clears nothing (T34-fix): a link
-  // that flapped under a still-standing closure would make the banner flicker
-  // away and back.
-  const closedSessions = new Map<string, ClosedSessionRecord['reason']>()
-  // T73-fix: waiters for "a closed-session record was just cleared" — the
-  // quiet session/follow hold (rewriteUpstream) ends its silence the moment
-  // the session it holds for is served again, so a re-enabled remote comes
-  // back with a fresh history instead of staying blind under its banner.
-  const closedClearWaiters = new Set<() => void>()
-  // The last successfully fetched SERVER model catalog (T52-fix), kept for
-  // the offline merges of the `session/modelCatalog` route below — cleared
-  // on a pairing wall (eagerly, by the T52-fix2 catalog watcher; the route's
-  // own drop is the backstop) and never served for another server's id (see the
-  // route's doc). Only an in-memory value: the groups are display data and
-  // a reload refetches them anyway. Since T52-fix3 it feeds ONLY this route:
-  // the modelSelection provider rewrites are unconditional again (the host's
-  // projection store is first-write-wins per seq, so a catalog-gated rewrite
-  // would poison the store — see virtualizeModelSelectionValue), and the
-  // `groups` membership set is gone with the gate.
-  let serverCatalogCache: { identity: MergerIdentity; value: unknown } | undefined
-  /**
-   * The serving generation, bumped on every pairing wall (`unpaired` /
-   * `revoked`, T52-fix3): a catalog fetch that was IN FLIGHT when the wall
-   * rose must not write its answer back — the wall's groups must not outlive
-   * it, and a late write would resurrect them under the offline merge below.
-   * Both cache writes (the proactive fetch here, the route's own fetch)
-   * snapshot the counter before invoking and compare before storing; a
-   * mismatched answer is silently dropped — it is not a fault, the next
-   * serving period fetches fresh anyway.
-   */
-  let catalogGeneration = 0
-  const rememberServerCatalog = (identity: MergerIdentity, value: unknown, generation: number): void => {
-    if (generation !== catalogGeneration) return
-    serverCatalogCache = { identity, value }
+  const waitAny = async (): Promise<void> => {
+    await new Promise<void>((resolve) => {
+      onlineWaiters.push(resolve)
+    })
   }
-  /** One server-catalog fetch whose answer only feeds the cache (T52-fix2):
-   * the proactive pull that runs as soon as the relay serves — and once at
-   * install when the relay already serves (subscribe replays no state —
-   * relay-client.ts setState returns on a same-state write — so the
-   * subscription alone would miss an install-into-online). Failures are
-   * diagnostics-ring entries, nothing else (the route's own fetch is the
-   * user-visible path and answers local-only there). */
-  const fetchServerCatalog = (identity: MergerIdentity): void => {
-    const generation = catalogGeneration
-    void relay.invoke('session', 'modelCatalog', {}, undefined).then(
-      (value) => {
-        rememberServerCatalog(identity, value, generation)
-      },
-      (error: unknown) => {
-        recordFailure('session/modelCatalog', error instanceof RelayError ? error.code : 'internal')
-      },
-    )
+  // The orchestrator's LOCAL truth, folded from every local frame — the one
+  // source the canonical composition reads its local lists from (a slot's
+  // merger keeps its own copy only for its discarded single-server frames).
+  let localSeen = false
+  let localBaselineFrame: unknown = undefined
+  let localLists = { orderIds: [], archivedIds: [], pinnedIds: [] } as { orderIds: string[]; archivedIds: string[]; pinnedIds: string[] }
+
+  const annotationOf = (client: RelayClient): MergerAnnotation => {
+    const state = client.state
+    if (state === 'revoked') return 'revoked'
+    if (state === 'unpaired') return 'unpaired'
+    if (state !== 'online') return 'offline'
+    const different = client.compat?.different
+    return different !== undefined && different.length > 0 ? 'mismatch' : 'none'
   }
-  // The catalog watcher (T52-fix2). The subscription fires on the real
-  // online transitions (first handshake, every recovery) — and since T59
-  // also on name-only notifications, which arrive with the state still
-  // `online` and are deduped by the same refreshKey/stateSeen gates above.
-  // The install-time check below covers an install into an already-online
-  // relay. `unpaired` / `revoked`
-  // drop the cache the same way the catalog route does lazily — the wall's
-  // groups must not outlive it — and bump the generation so an in-flight
-  // fetch cannot write the old catalog back (T52-fix3). Faults stay
-  // contained: the sync body cannot throw, and the fetch settles through
-  // .then/.catch above.
-  let offCatalogWatch: (() => void) | undefined
-  try {
-    offCatalogWatch = relay.subscribe((state) => {
-      if (state === 'unpaired' || state === 'revoked') {
-        catalogGeneration += 1
-        serverCatalogCache = undefined
-        return
-      }
-      if (state !== 'online') return
-      const identity = relayIdentityOf(relay)
-      if (identity !== undefined) fetchServerCatalog(identity)
-    })
-    // Install into an already-serving relay: subscribe replayed nothing, so
-    // the transition-based fetch would wait for the NEXT flap — fill the
-    // cache now instead (T52-fix3).
-    if (relay.state === 'online') {
-      const identity = relayIdentityOf(relay)
-      if (identity !== undefined) fetchServerCatalog(identity)
+  const workspaceMergerOf = (slot: PoolGlobalSlot): WorkspaceMerger | undefined =>
+    slot.kind === 'workspace' ? (slot.merger as WorkspaceMerger) : undefined
+
+  const pushOut = (frames: readonly unknown[]): void => {
+    if (frames.length === 0) return
+    for (const frame of frames) channel.push(frame)
+    if (isWorkspace) {
+      const ids = virtualSessionIdsInWorkspaceFrames(frames)
+      if (ids.length > 0) deps.summarySync.noteForwardedSessionIds(ids)
     }
-  } catch (error) {
-    // Subscription failed: the cache still fills whenever the UI opens a
-    // dropdown (the route's own fetch), only later.
-    log?.('client catalog watcher unavailable: %s', messageOf(error))
   }
-  const registerClosed = (sessionId: string, reason: ClosedSessionRecord['reason']): void => {
-    closedSessions.delete(sessionId)
-    if (closedSessions.size >= MAX_CLOSED_SESSIONS) {
-      const oldest = closedSessions.keys().next()
-      if (oldest.done !== true) closedSessions.delete(oldest.value)
+  const orderedRemoteParts = (): { slot: PoolGlobalSlot; remote: RemoteWorkspaceContribution }[] => {
+    const out: { slot: PoolGlobalSlot; remote: RemoteWorkspaceContribution }[] = []
+    if (!isWorkspace) return out
+    for (const entry of pool.entries()) {
+      if (entry.serverId === undefined) continue
+      const slot = slots.get(entry.serverId)
+      const merger = slot !== undefined ? workspaceMergerOf(slot) : undefined
+      if (slot === undefined || merger === undefined) continue
+      out.push({ slot, remote: merger.parts().remote })
     }
-    closedSessions.set(sessionId, reason)
+    return out
   }
-  const clearClosed = (virtuals: VirtualParts[]): void => {
-    let cleared = false
-    for (const parts of virtuals) {
-      if (closedSessions.delete(toVirtual(parts.serverId, parts.id))) cleared = true
-    }
-    if (cleared) for (const waiter of [...closedClearWaiters]) waiter()
+  /** The canonical merged global frames over ALL current slots — pairing
+   * order, local first. Only past the local baseline: before it the slots
+   * cache their remote state and the frames would order workspaces the
+   * local baseline would immediately erase. */
+  const composedFrames = (): { order: unknown; archived: unknown; pinned: unknown } | undefined => {
+    if (!localSeen || !isWorkspace) return undefined
+    const parts = orderedRemoteParts()
+    return composeMergedWorkspaceFrames(localLists, parts.map((part) => part.remote))
   }
-  let installed = true
-  let selfCheck: SelfCheckResult | undefined
-
-  /**
-   * Reload overlay, for the record (CP4): the theoretical hazard is installing
-   * a NEW wrapper while an OLD one is still installed, so each captures the
-   * other and the older survives as a live layer. Cordis `fiber.restart()`
-   * disposes the old fiber FIRST (its effect calls {@link InterceptHandle.uninstall},
-   * restoring the saved property) and only then applies the new row — the
-   * overlay ordering never happens today, so there is nothing to absorb at
-   * install time. Detection is also not cheaply implementable: a reloaded row
-   * loads a FRESH module instance, so a stale wrapper shares no mark with the
-   * new one — telling "ours, from a dead generation" apart from another
-   * plugin's wrapper would take a process-wide registry, which the comment
-   * above argues is not worth it while the ordering cannot occur. The
-   * `installed === false → inert passthrough` rule below is the safety net
-   * for the ordering that CAN happen: a later plugin wrapping OVER us and
-   * keeping a reference past our uninstall.
-   *
-   * Save the CURRENT value per property (possibly another plugin's wrapper —
-   * shape note "own-property"), falling back to the prototype method only
-   * when the current value is not callable. Uninstall restores the saved
-   * own state verbatim: value if there was one, absence if not.
-   */
-  const saved: Record<string, { existed: boolean; value: unknown }> = {}
-  const chainTarget: Record<string, unknown> = {}
-  for (const name of ['openWireStream', 'dispatchRpc']) {
-    const existed = Object.prototype.hasOwnProperty.call(gateway, name)
-    const value = existed ? gateway[name] : undefined
-    saved[name] = { existed, value }
-    chainTarget[name] = typeof value === 'function' ? value : Object.getPrototypeOf(raw)?.[name]
+  const pushCanonicalTrio = (): void => {
+    const composed = composedFrames()
+    if (composed !== undefined) pushOut([composed.order, composed.archived, composed.pinned])
   }
-  // Filled in below, once the wrapper functions exist: uninstall may only
-  // touch a property that still holds OUR wrapper.
-  const wrappers: Record<string, unknown> = {}
 
-  const recordFailure = (endpoint: string, code: string): void => {
-    if (failures.length >= MAX_FAILURES) failures.shift()
-    failures.push({ time: new Date().toISOString(), endpoint, code })
-    // T42: validation-shaped refusals additionally land in the incompatible
-    // ring — every remote failure funnels through this one function, so the
-    // classification cannot drift between the invoke and stream routes.
-    if (!INCOMPATIBLE_CALL_CODES.has(code)) return
-    if (incompatible.length >= MAX_INCOMPATIBLE_CALLS) incompatible.shift()
-    incompatible.push({ time: Date.now(), endpoint, code })
+  // -- current-session judging (T58/T62), across every slot ------------------
+  let lastLang: InterceptLang = resolveInterceptLang(deps.lang)
+  const informCurrentSession = (): void => {
+    const nextLang = resolveInterceptLang(deps.lang)
+    if (nextLang !== lastLang) {
+      lastLang = nextLang
+      if (isWorkspace) {
+        let langUpserted = false
+        for (const slot of [...slots.values()]) {
+          const merger = workspaceMergerOf(slot)
+          if (merger === undefined) continue
+          const frames = merger.onStatusChanged()
+          if (frames.length > 0) {
+            pushOut(frames.filter((frame) => isPlainObject(frame) && frame.type === 'upsert'))
+            langUpserted = true
+          }
+        }
+        if (langUpserted) pushCanonicalTrio()
+      }
+    }
+    const read = deps.getCurrentSession()
+    if (read.kind === 'unavailable') return
+    let changed = false
+    for (const slot of [...slots.values()]) {
+      if (slot.merger.setCurrentSession(read.kind === 'open' ? read.sessionId : undefined).length > 0) changed = true
+    }
+    if (!changed || !localSeen || !isWorkspace) return
+    const parts = orderedRemoteParts()
+    pushOut([composeMergedWorkspaceFrames(localLists, parts.map((part) => part.remote)).archived])
   }
-
-  const failEnvelope = (
-    endpoint: string,
-    code: string,
-    text: string,
-  ): { ok: false; error: { code: string; message: string; details: Record<string, unknown> } } => {
-    recordFailure(endpoint, code)
-    // `details: {}` is load-bearing: the UI's server-response parser throws
-    // `invalid server-response failure` on a details-less error (and the
-    // gateway's rpcErrorSchema demands the same shape).
-    return { ok: false, error: { code, message: text, details: {} } }
+  const anyPendingHide = (): boolean => {
+    for (const slot of [...slots.values()]) {
+      if (slot.merger.hasPendingHide) return true
+    }
+    return false
+  }
+  let sessionPoll: unknown = undefined
+  const pollCurrentSession = (): void => {
+    sessionPoll = undefined
+    if (!alive) return
+    if (anyPendingHide()) informCurrentSession()
+    if (alive && anyPendingHide()) sessionPoll = clock.setTimeout(pollCurrentSession, CURRENT_SESSION_POLL_MS)
+  }
+  const ensureSessionPoll = (): void => {
+    if (sessionPoll === undefined && alive && anyPendingHide()) {
+      sessionPoll = clock.setTimeout(pollCurrentSession, CURRENT_SESSION_POLL_MS)
+    }
   }
 
-  /**
-   * The shared validation both routes apply before forwarding: the relay
-   * client must have completed a handshake (else `remote-offline` — nothing
-   * is connected yet, which is not the same as being pointed at the wrong
-   * server), every virtual id in the call must belong to ONE server, and to
-   * the server the handshake named (`remote-mismatch`); the method must be
-   * in the table (`remote-unsupported`). A refusal is recorded once, here,
-   * by the caller passing it through {@link failEnvelope}.
-   */
-  type Verdict = { ok: true; serverId: string } | { ok: false; code: string; message: string }
-  function validate(endpoint: string, virtuals: VirtualParts[]): Verdict {
-    const first = virtuals[0].serverId
-    const current = getServerId()
-    if (current === undefined) return { ok: false, code: 'remote-offline', message: '尚未连接到服务端' }
-    if (virtuals.some((parts) => parts.serverId !== first) || current !== first) {
-      return { ok: false, code: 'remote-mismatch', message: '此远程会话属于其他主服务端' }
+  // -- slot lifecycle ----------------------------------------------------------
+  const removeSlot = (serverId: string, slot: PoolGlobalSlot): void => {
+    slots.delete(serverId)
+    slot.removed = true
+    slot.offState()
+    slot.controller?.abort()
+    if (slot.inventory !== undefined) {
+      slot.inventory.dispose()
+      slot.inventory = undefined
     }
-    if (CLIENT_METHOD_FIELDS[endpoint] === undefined) {
-      return { ok: false, code: 'remote-unsupported', message: '此功能暂不支持远程会话' }
+    // Only THIS server's shown groups leave; the canonical trio then re-airs
+    // the merged order/archived/pinned over the surviving slots (the
+    // merger's own trailing local-only restores are superseded by it).
+    if (!isWorkspace) return
+    const merger = slot.merger as WorkspaceMerger
+    const gone = merger.onRemoteGone()
+    pushOut(gone.filter((frame) => isPlainObject(frame) && frame.type === 'remove'))
+    pushCanonicalTrio()
+  }
+  const applySlotAnnotation = (slot: PoolGlobalSlot, next: MergerAnnotation): void => {
+    if (next === slot.annotation) return
+    slot.annotation = next
+    slot.merger.setStatus(next)
+    if (!isWorkspace) return
+    const merger = slot.merger as WorkspaceMerger
+    const frames = merger.onStatusChanged()
+    if (frames.length > 0) {
+      pushOut(frames.filter((frame) => isPlainObject(frame) && frame.type === 'upsert'))
+      pushCanonicalTrio()
+    }
+  }
+  const refreshOneViewName = (slot: PoolGlobalSlot, nextName: string): void => {
+    slot.viewName = nextName
+    slot.merger.retarget({ serverId: slot.serverId, serverName: nextName })
+    if (!isWorkspace) return
+    const merger = slot.merger as WorkspaceMerger
+    const frames = merger.onServerRenamed()
+    if (frames.length > 0) {
+      pushOut(frames)
+      pushCanonicalTrio()
+    }
+  }
+  const refreshViewNames = (): void => {
+    for (const entry of pool.entries()) {
+      const slot = entry.serverId !== undefined ? slots.get(entry.serverId) : undefined
+      if (slot !== undefined && slot.viewName !== entry.displayName) refreshOneViewName(slot, entry.displayName)
     }
-    return { ok: true, serverId: first }
   }
 
-  /**
-   * The T32 `$events/result` split: an answer whose eventId is VIRTUAL
-   * belongs to a forwarded remote event and must NOT reach the local
-   * gateway (its own `$events` never delivered it — the local dispatcher
-   * would answer with its `no active event stream` failure). The virtual
-   * id goes back to the original, the local payload's clientId (the local
-   * stream's own) is discarded — the relay server composes the gateway
-   * payload from ITS subscription's clientId — and the outcome rides
-   * verbatim. Anything else, including a malformed payload, is the local
-   * gateway's business.
-   */
-  function forwardEventResult(payload: unknown, signal: AbortSignal | undefined, peer: unknown): unknown {
-    const args = argsOf(payload)
+  const pumpSlot = async (slot: PoolGlobalSlot): Promise<void> => {
+    // Whole body guarded: ANY escape stops THIS server's leg only.
+    try {
+      while (alive && !slot.removed) {
+        if (slot.client.state !== 'online') {
+          await waitAny()
+          continue
+        }
+        const controller = new AbortController()
+        slot.controller = controller
+        try {
+          const stream = slot.client.openStream(namespace, method, {}, controller.signal)
+          let served = false
+          for await (const frame of stream) {
+            // Post-abort lines the transport already decoded must not reach
+            // the merger (same discipline as the single-server pumps).
+            if (!alive || slot.removed || controller.signal.aborted) break
+            if (!served) {
+              served = true
+              slot.reopenDelayMs = REMOTE_REOPEN_FIRST_MS
+            }
+            informCurrentSession()
+            const out = slot.merger.onRemote(frame)
+            if (out.length > 0) {
+              if (isWorkspace) {
+                pushOut(out.filter((outFrame) => isPlainObject(outFrame) && (outFrame.type === 'upsert' || outFrame.type === 'remove')))
+                pushCanonicalTrio()
+              } else {
+                pushOut(out)
+              }
+            }
+            ensureSessionPoll()
+          }
+        } catch (error) {
+          if (alive && !slot.removed && !controller.signal.aborted && signal?.aborted !== true) {
+            recordFailure(endpoint, error instanceof RelayError ? error.code : 'internal')
+          }
+        } finally {
+          if (slot.controller === controller) slot.controller = undefined
+        }
+        if (!alive || slot.removed) return
+        slot.merger.onRemoteDown()
+        if (slot.client.state === 'online') {
+          await waitReopen(clock, waitAny, slot.reopenDelayMs)
+          slot.reopenDelayMs = Math.min(slot.reopenDelayMs * 2, REMOTE_REOPEN_MAX_MS)
+          continue
+        }
+        await waitAny()
+      }
+    } catch (error) {
+      if (alive) onDiagnostic(`remote leg of ${slot.serverId} stopped: ${messageOf(error)}`)
+    }
+  }
+
+  /** Re-read pool.entries(): create slots for new handshook servers (in
+   * pairing order), refresh display names, remove slots whose server left.
+   * Also heals a re-handshake that renamed the entry's serverId. */
+  const scanSlots = (): void => {
+    const seen = new Set<string>()
+    for (const entry of pool.entries()) {
+      const serverId = entry.serverId
+      if (serverId === undefined) continue
+      seen.add(serverId)
+      const existing = slots.get(serverId)
+      if (existing !== undefined) {
+        if (existing.viewName !== entry.displayName) refreshOneViewName(existing, entry.displayName)
+        continue
+      }
+      const inventory = isWorkspace && deps.createSessionInventorySlot !== undefined
+        ? deps.createSessionInventorySlot(serverId)
+        : undefined
+      const merger = isWorkspace
+        ? createWorkspaceMerger({
+            serverId,
+            serverName: entry.displayName,
+            onDiagnostic,
+            now: clock.now,
+            lang: deps.lang,
+            ...(inventory !== undefined ? { onKnownSessions: (ids: ReadonlySet<string>) => inventory.replace(ids) } : {}),
+          })
+        : createControlMerger({ serverId, serverName: entry.displayName, onDiagnostic })
+      const slot: PoolGlobalSlot = {
+        kind: isWorkspace ? 'workspace' : 'control',
+        serverId,
+        entryId: entry.entryId,
+        client: entry.client,
+        merger,
+        viewName: entry.displayName,
+        controller: undefined,
+        offState: () => {},
+        annotation: annotationOf(entry.client),
+        reopenDelayMs: REMOTE_REOPEN_FIRST_MS,
+        removed: false,
+        inventory,
+      }
+      merger.setStatus(slot.annotation)
+      slot.offState = slot.client.subscribe((state) => {
+        try {
+          // The set itself may have changed (a dedupe renamed the entry's
+          // serverId, a rename moved the display name) — re-scan first.
+          scanSlots()
+          if (state === 'unpaired' || state === 'revoked') {
+            applySlotAnnotation(slot, annotationOf(slot.client))
+            slot.merger.onRemoteDown()
+            slot.controller?.abort()
+            return
+          }
+          applySlotAnnotation(slot, annotationOf(slot.client))
+          if (state === 'online') refreshViewNames()
+        } catch (error) {
+          log?.('client multi merge slot state handler failed on %s: %s', serverId, messageOf(error))
+        } finally {
+          flushWaiters()
+        }
+      })
+      slots.set(serverId, slot)
+      // A slot born mid-stream missed the local baseline — replay it (its
+      // output is discarded; the replay only sets the merger's localSeen and
+      // local lists). Runs BEFORE the pump starts, so the buffer is empty.
+      if (localBaselineFrame !== undefined) {
+        for (const out of slot.merger.onLocal(localBaselineFrame)) void out
+      }
+      void pumpSlot(slot)
+    }
+    for (const [serverId, slot] of [...slots]) {
+      if (!seen.has(serverId)) removeSlot(serverId, slot)
+    }
+  }
+
+  // -- local frames -------------------------------------------------------------
+  const pushLocalWorkspace = (frame: unknown): void => {
+    localLists = localWorkspaceLists(frame, localLists)
+    // Every slot's merger must observe the local frames too — its localSeen
+    // gate (nothing leaves its onRemote before the local baseline passed)
+    // and its own local lists live there. Its OUTPUT is discarded: the
+    // single-server global frames (its merged order/archived/pinned) are
+    // superseded by the canonical composition over ALL slots.
+    for (const slot of [...slots.values()]) {
+      for (const out of slot.merger.onLocal(frame)) void out
+    }
+    if (!isPlainObject(frame)) {
+      pushOut([frame])
+      return
+    }
+    if (frame.type === 'baseline') {
+      localSeen = true
+      localBaselineFrame = frame
+      const parts = orderedRemoteParts()
+      const remotes = parts.map((part) => part.remote)
+      const hasRemote = remotes.some(
+        (remote) => remote.orderIds.length + remote.archivedIds.length + remote.pinnedIds.length + remote.workspaces.length > 0,
+      )
+      if (!hasRemote) {
+        pushOut([frame])
+        return
+      }
+      const value = isPlainObject(frame.value) ? frame.value : {}
+      const items = Array.isArray(value.items) ? value.items : []
+      const composed = composeMergedWorkspaceFrames(localLists, remotes)
+      pushOut([
+        {
+          ...frame,
+          value: {
+            ...value,
+            items: [...items, ...composed.workspaces],
+            archivedSessionIds: composed.archived.archivedSessionIds,
+            pinnedSessionIds: composed.pinned.pinnedSessionIds,
+          },
+        },
+        ...composed.workspaces.map((workspace) => ({ type: 'upsert', workspace })),
+      ])
+      return
+    }
+    const remotes = orderedRemoteParts().map((part) => part.remote)
+    if (frame.type === 'order') {
+      if (!remotes.some((remote) => remote.orderIds.length > 0)) {
+        pushOut([frame])
+        return
+      }
+      pushOut([composeMergedWorkspaceFrames(localLists, remotes).order])
+      return
+    }
+    if (frame.type === 'archived') {
+      if (!remotes.some((remote) => remote.archivedIds.length > 0)) {
+        pushOut([frame])
+        return
+      }
+      pushOut([composeMergedWorkspaceFrames(localLists, remotes).archived])
+      return
+    }
+    if (frame.type === 'pinned') {
+      if (!remotes.some((remote) => remote.pinnedIds.length > 0)) {
+        pushOut([frame])
+        return
+      }
+      pushOut([composeMergedWorkspaceFrames(localLists, remotes).pinned])
+      return
+    }
+    // upsert / remove / anything else local: purely local facts.
+    pushOut([frame])
+  }
+  const pushLocalControl = (frame: unknown): void => {
+    if (isPlainObject(frame) && frame.type === 'baseline') {
+      pushOut([frame])
+      // Each slot's buffered pre-baseline projections flush behind it (the
+      // slots' own baseline copies are the SAME frame object — skip those).
+      for (const slot of [...slots.values()]) {
+        for (const out of slot.merger.onLocal(frame)) {
+          if (out !== frame) pushOut([out])
+        }
+      }
+      return
+    }
+    pushOut([frame])
+    for (const slot of [...slots.values()]) slot.merger.onLocal(frame)
+  }
+
+  const offCurrentSession = deps.watchCurrentSession(informCurrentSession)
+  const offUninstall = deps.watchUninstall(() => {
+    try {
+      const read = deps.getCurrentSession()
+      for (const slot of [...slots.values()]) {
+        slot.merger.setCurrentSession(read.kind === 'open' ? read.sessionId : undefined)
+        applySlotAnnotation(slot, 'unpaired')
+        slot.merger.onRemoteDown()
+        slot.controller?.abort()
+      }
+    } catch {
+      // ignore teardown errors
+    } finally {
+      flushWaiters()
+    }
+  })
+  const offPool = deps.watchPool(() => {
+    try {
+      scanSlots()
+      refreshViewNames()
+    } catch (error) {
+      log?.('client multi merge pool rescan failed on %s: %s', endpoint, messageOf(error))
+    } finally {
+      flushWaiters()
+    }
+  })
+
+  const onExternalAbort = (): void => {
+    alive = false
+    for (const slot of [...slots.values()]) slot.controller?.abort()
+    flushWaiters()
+    channel.end()
+  }
+  if (signal !== undefined) signal.addEventListener('abort', onExternalAbort)
+
+  scanSlots()
+  informCurrentSession()
+
+  const localIterator = local[Symbol.asyncIterator]()
+  const pumpLocal = async (): Promise<void> => {
+    try {
+      while (alive) {
+        const result = await localIterator.next()
+        if (result.done === true) break
+        informCurrentSession()
+        if (isWorkspace) pushLocalWorkspace(result.value)
+        else pushLocalControl(result.value)
+        ensureSessionPoll()
+      }
+    } catch (error) {
+      // The local stream is the one the UI opened: its failure is the
+      // merged stream's failure (a remote death never is).
+      if (alive) channel.fail(error)
+      return
+    }
+    if (!alive) return
+    alive = false
+    for (const slot of [...slots.values()]) slot.controller?.abort()
+    flushWaiters()
+    channel.end()
+  }
+
+  void pumpLocal()
+  try {
+    while (true) {
+      const result = await channel.next()
+      if (result.done === true) break
+      yield result.value
+    }
+  } finally {
+    alive = false
+    if (sessionPoll !== undefined) clock.clearTimeout(sessionPoll)
+    offCurrentSession()
+    offUninstall()
+    offPool()
+    if (signal !== undefined) signal.removeEventListener('abort', onExternalAbort)
+    for (const slot of [...slots.values()]) {
+      slot.removed = true
+      slot.offState()
+      slot.controller?.abort()
+      slot.inventory?.dispose()
+    }
+    slots.clear()
+    flushWaiters()
+    void Promise.resolve(localIterator.return?.(undefined)).catch(() => {})
+  }
+}
+
+interface PoolEventSlot {
+  serverId: string
+  client: RelayClient
+  controller: AbortController | undefined
+  offState: () => void
+  /** This server's shown-and-uncanceled virtual eventIds — the orphan-close
+   * record. PER SLOT by design: a leg dying closes only its own prompts. */
+  shownEvents: Set<string>
+  reopenDelayMs: number
+  removed: boolean
+  displayName: string
+  /** T52 refresh key for this slot (its identity while serving). */
+  notedIdentity: string | undefined
+  stateSeen: RelayState | undefined
+  statusInFlight: boolean
+  statusPending: boolean
+  statusDeferred: boolean
+}
+
+interface MergedEventsStreamMultiDeps {
+  local: AsyncIterable<unknown>
+  pool: RelayPool
+  signal: AbortSignal | undefined
+  recordFailure: (endpoint: string, code: string) => void
+  log: ((format: string, ...args: unknown[]) => void) | undefined
+  clock: RelayClock
+  summarySync: SessionSummarySync
+  watchPool(fn: () => void): () => void
+}
+
+/**
+ * The pool-mode merged `$events` stream: one `$zr/events` leg per pooled
+ * server, each with its own orphan-close record. The T52 catalog refresh
+ * fires whenever any slot's serving identity appears, changes, or leaves;
+ * the T63/T65 summary sync and the T75 status sync fetch from the OWNING
+ * server of each id (virtual ids carry the serverId), per slot on its own
+ * serving periods.
+ */
+async function* mergedEventsStreamMulti(deps: MergedEventsStreamMultiDeps): AsyncGenerator<unknown, void, undefined> {
+  const { local, pool, signal, recordFailure, log, clock } = deps
+  if (signal?.aborted === true) return
+  const channel = createFrameChannel()
+  let alive = true
+  const slots = new Map<string, PoolEventSlot>()
+  const onlineWaiters: (() => void)[] = []
+  const flushWaiters = (): void => {
+    for (const wake of onlineWaiters.splice(0)) wake()
+  }
+  const waitAny = async (): Promise<void> => {
+    await new Promise<void>((resolve) => {
+      onlineWaiters.push(resolve)
+    })
+  }
+  let localOpened = false
+  let deferredRefresh = false
+  const pushRefresh = (): void => {
+    if (!localOpened) {
+      deferredRefresh = true
+      return
+    }
+    channel.push(catalogRefreshFrame())
+  }
+  const noteSlotIdentity = (slot: PoolEventSlot): void => {
+    const key = slot.client.state === 'online' ? `${slot.serverId}\u0000${slot.displayName}` : undefined
+    if (key === slot.notedIdentity) return
+    slot.notedIdentity = key
+    if (key !== undefined) pushRefresh()
+  }
+
+  // -- T63/T65/T75 bookkeeping: global maps over VIRTUAL ids (globally
+  // unique across servers), per-slot fetch rounds. Same discipline as the
+  // single-server stream — see mergedEventsStream for the full story.
+  const announced = new Set<string>()
+  const askAttempts = new Map<string, number>()
+  const askedForGood = new Set<string>()
+  const retryAt = new Map<string, number>()
+  const MAX_ASK_ATTEMPTS = 3
+  const ASK_RETRY_FIRST_MS = 2_000
+  const ASK_RETRY_SECOND_MS = 10_000
+  let retryTimer: unknown = undefined
+  let midFlightBatches: string[] = []
+  let askingNow: string[] = []
+  let summarySyncInFlight = false
+  let deferredSummarySync = false
+  const latestLiveStatus = new Map<string, boolean>()
+  let statusSeq = 0
+  const liveStatusSeq = new Map<string, number>()
+
+  const scheduleRetry = (): void => {
+    if (retryTimer !== undefined || retryAt.size === 0) return
+    const earliest = Math.min(...retryAt.values())
+    retryTimer = clock.setTimeout(() => {
+      retryTimer = undefined
+      if (!alive) return
+      const nowMs = clock.now()
+      const due: string[] = []
+      for (const [id, at] of retryAt) {
+        if (at <= nowMs) {
+          retryAt.delete(id)
+          due.push(id)
+        }
+      }
+      if (due.length > 0) runSummarySync(due)
+    }, Math.max(0, earliest - clock.now()))
+  }
+  const runSummarySync = (triggerIds: readonly string[] = []): void => {
+    if (!alive) return
+    if (!localOpened) {
+      deferredSummarySync = true
+      return
+    }
+    if (summarySyncInFlight) {
+      midFlightBatches.push(...triggerIds)
+      return
+    }
+    const rounds: { slot: PoolEventSlot; ids: string[] }[] = []
+    if (triggerIds.length === 0) {
+      for (const slot of [...slots.values()]) {
+        if (slot.client.state === 'online') rounds.push({ slot, ids: [] })
+      }
+    } else {
+      for (const id of triggerIds) {
+        const parts = fromVirtual(id)
+        if (parts === undefined) continue
+        const slot = slots.get(parts.serverId)
+        if (slot === undefined || slot.client.state !== 'online') continue
+        let round = rounds.find((candidate) => candidate.slot === slot)
+        if (round === undefined) {
+          round = { slot, ids: [] }
+          rounds.push(round)
+        }
+        round.ids.push(id)
+      }
+    }
+    if (rounds.length === 0) return
+    summarySyncInFlight = true
+    askingNow = [...triggerIds]
+    for (const round of rounds) {
+      for (const id of round.ids) askAttempts.set(id, (askAttempts.get(id) ?? 0) + 1)
+    }
+    void Promise.all(
+      rounds.map((round) =>
+        round.slot.client
+          .invoke('session', 'list', { _request: {} }, undefined)
+          .then(
+            (value) => ({ round, value, error: undefined as unknown }),
+            (error: unknown) => ({ round, value: undefined, error }),
+          ),
+      ),
+    ).then((results) => {
+      summarySyncInFlight = false
+      if (!alive) return
+      askingNow = []
+      for (const result of results) {
+        if (result.error !== undefined) {
+          recordFailure('session/list', result.error instanceof RelayError ? result.error.code : 'internal')
+          continue
+        }
+        const frames = sessionSummaryAddedFrames(result.value, result.round.slot.serverId)
+        const returned = new Set<string>()
+        for (const frame of frames) {
+          const row = (frame as { args: unknown[] }).args[0]
+          const rowId = isPlainObject(row) && typeof row.sessionId === 'string' ? row.sessionId : undefined
+          if (rowId === undefined) continue
+          returned.add(rowId)
+          if (announced.has(rowId)) continue
+          announced.add(rowId)
+          channel.push(frame)
+          const liveRunning = latestLiveStatus.get(rowId)
+          if (liveRunning !== undefined && liveRunning !== (isPlainObject(row) && row.running === true)) {
+            channel.push({ type: 'emit', event: 'api-session/status', args: [rowId, liveRunning] })
+          }
+        }
+        for (const id of result.round.ids) {
+          if (returned.has(id)) {
+            retryAt.delete(id)
+            continue
+          }
+          const attempts = askAttempts.get(id) ?? 0
+          if (attempts >= MAX_ASK_ATTEMPTS) askedForGood.add(id)
+          else retryAt.set(id, clock.now() + (attempts <= 1 ? ASK_RETRY_FIRST_MS : ASK_RETRY_SECOND_MS))
+        }
+      }
+      scheduleRetry()
+      const queued = midFlightBatches
+      midFlightBatches = []
+      if (queued.length > 0) runSummarySync(queued)
+    })
+  }
+  const handleForwardedBatch = (ids: readonly string[]): void => {
+    if (!ids.some((id) => !announced.has(id) && !askedForGood.has(id) && !retryAt.has(id))) return
+    runSummarySync(ids)
+  }
+  /** T75 per slot: re-push every row's running flag from a fresh snapshot
+   * of THIS server when its serving period starts. */
+  const runStatusSync = (slot: PoolEventSlot): void => {
+    if (!alive) return
+    if (!localOpened) {
+      slot.statusDeferred = true
+      return
+    }
+    if (slot.statusInFlight) {
+      slot.statusPending = true
+      return
+    }
+    if (slot.client.state !== 'online') return
+    slot.statusInFlight = true
+    // The race guard arms here (see the single-server stream): only frames
+    // arriving after this point outrank the snapshot — older records have a
+    // lower seq than startSeq and never block.
+    const startSeq = ++statusSeq
+    void slot.client.invoke('session', 'list', { _request: {} }, undefined).then(
+      (value) => {
+        slot.statusInFlight = false
+        if (!alive) return
+        const rows = isPlainObject(value) && Array.isArray(value.items) ? value.items : []
+        for (const row of rows) {
+          if (!isPlainObject(row) || typeof row.sessionId !== 'string' || row.sessionId === '') continue
+          if ((liveStatusSeq.get(row.sessionId) ?? 0) > startSeq) continue
+          channel.push({
+            type: 'emit',
+            event: 'api-session/status',
+            args: [toVirtual(slot.serverId, row.sessionId), row.running === true],
+          })
+        }
+        if (slot.statusPending) {
+          slot.statusPending = false
+          runStatusSync(slot)
+        }
+      },
+      (error: unknown) => {
+        slot.statusInFlight = false
+        if (!alive) return
+        recordFailure('session/list', error instanceof RelayError ? error.code : 'internal')
+        if (slot.statusPending) {
+          slot.statusPending = false
+          runStatusSync(slot)
+        }
+      },
+    )
+  }
+  /** One slot's fresh serving period: the ask bookkeeping gets another
+   * chance, and this server's rows are re-synced (statuses first). */
+  const noteFirstOnline = (slot: PoolEventSlot): void => {
+    askedForGood.clear()
+    askAttempts.clear()
+    retryAt.clear()
+    latestLiveStatus.clear()
+    if (retryTimer !== undefined) {
+      clock.clearTimeout(retryTimer)
+      retryTimer = undefined
+    }
+    runStatusSync(slot)
+    runSummarySync()
+  }
+
+  const pumpSlot = async (slot: PoolEventSlot): Promise<void> => {
+    try {
+      while (alive && !slot.removed) {
+        if (slot.client.state !== 'online') {
+          await waitAny()
+          continue
+        }
+        const controller = new AbortController()
+        slot.controller = controller
+        try {
+          const stream = slot.client.openStream('$zr', 'events', {}, controller.signal)
+          let served = false
+          for await (const frame of stream) {
+            if (!alive || slot.removed || controller.signal.aborted) break
+            if (!served) {
+              served = true
+              slot.reopenDelayMs = REMOTE_REOPEN_FIRST_MS
+            }
+            const rewritten = rewriteRemoteEventFrame(frame, slot.serverId)
+            if (rewritten === null) continue
+            // T75 race guard + PB-26a live status, exactly as the single
+            // server stream keeps them — keyed by ids that are already
+            // globally unique (virtual or original-then-virtualized).
+            if (isPlainObject(frame) && frame.type === 'emit' && frame.event === 'api-session/status') {
+              const rowId = Array.isArray(frame.args) ? frame.args[0] : undefined
+              if (typeof rowId === 'string' && rowId !== '') liveStatusSeq.set(rowId, ++statusSeq)
+              const args = isPlainObject(rewritten) && Array.isArray(rewritten.args) ? rewritten.args : undefined
+              const virtualId = args?.[0]
+              const running = args?.[1]
+              if (typeof virtualId === 'string' && typeof running === 'boolean') {
+                latestLiveStatus.set(virtualId, running)
+                if (!announced.has(virtualId)) handleForwardedBatch([virtualId])
+              }
+            }
+            const eventId =
+              isPlainObject(rewritten) && typeof rewritten.eventId === 'string' ? rewritten.eventId : undefined
+            if (eventId !== undefined) {
+              if (isPlainObject(frame) && frame.type === 'waterfall') {
+                if (slot.shownEvents.has(eventId)) continue
+                slot.shownEvents.add(eventId)
+              } else if (isPlainObject(frame) && frame.type === 'cancel') {
+                slot.shownEvents.delete(eventId)
+              }
+            }
+            channel.push(rewritten)
+          }
+        } catch (error) {
+          if (alive && !slot.removed && !controller.signal.aborted && signal?.aborted !== true) {
+            recordFailure('$zr/events', error instanceof RelayError ? error.code : 'internal')
+          }
+        } finally {
+          if (slot.controller === controller) slot.controller = undefined
+        }
+        // THIS leg is over — close only ITS prompts. A disconnect is not a
+        // verdict; the reopen re-delivers still-pending events under the
+        // SAME ids (the server prefixes them per subscription, so the
+        // virtual ids differ — DSH shows them fresh, the old cancels already
+        // closed the stale prompts).
+        for (const eventId of slot.shownEvents) channel.push({ type: 'cancel', eventId })
+        slot.shownEvents = new Set()
+        if (!alive || slot.removed) return
+        if (slot.client.state === 'online') {
+          await waitReopen(clock, waitAny, slot.reopenDelayMs)
+          slot.reopenDelayMs = Math.min(slot.reopenDelayMs * 2, REMOTE_REOPEN_MAX_MS)
+          continue
+        }
+        await waitAny()
+      }
+    } catch (error) {
+      if (alive) log?.('client events remote leg of %s stopped: %s', slot.serverId, messageOf(error))
+    }
+  }
+
+  const scanSlots = (): void => {
+    const seen = new Set<string>()
+    for (const entry of pool.entries()) {
+      const serverId = entry.serverId
+      if (serverId === undefined) continue
+      seen.add(serverId)
+      const existing = slots.get(serverId)
+      if (existing !== undefined) {
+        if (existing.displayName !== entry.displayName) {
+          existing.displayName = entry.displayName
+          noteSlotIdentity(existing)
+        }
+        continue
+      }
+      const slot: PoolEventSlot = {
+        serverId,
+        client: entry.client,
+        controller: undefined,
+        offState: () => {},
+        shownEvents: new Set(),
+        reopenDelayMs: REMOTE_REOPEN_FIRST_MS,
+        removed: false,
+        displayName: entry.displayName,
+        notedIdentity: undefined,
+        stateSeen: undefined,
+        statusInFlight: false,
+        statusPending: false,
+        statusDeferred: false,
+      }
+      slot.offState = slot.client.subscribe((state) => {
+        try {
+          const firstOnline = state === 'online' && slot.stateSeen !== 'online'
+          slot.stateSeen = state
+          if (state === 'unpaired' || state === 'revoked') {
+            slot.controller?.abort()
+            noteSlotIdentity(slot)
+            return
+          }
+          noteSlotIdentity(slot)
+          if (state === 'online' && firstOnline) noteFirstOnline(slot)
+        } catch (error) {
+          log?.('client events merge slot state handler failed on %s: %s', serverId, messageOf(error))
+        } finally {
+          flushWaiters()
+        }
+      })
+      slots.set(serverId, slot)
+      void pumpSlot(slot)
+      // Install into an already-serving server: subscribe replayed nothing.
+      if (slot.client.state === 'online') {
+        slot.stateSeen = 'online'
+        noteSlotIdentity(slot)
+        noteFirstOnline(slot)
+      }
+    }
+    for (const [serverId, slot] of [...slots]) {
+      if (!seen.has(serverId)) {
+        slots.delete(serverId)
+        slot.removed = true
+        slot.offState()
+        slot.controller?.abort()
+        // Only THIS server's pending prompts get the synthesized cancels.
+        for (const eventId of slot.shownEvents) channel.push({ type: 'cancel', eventId })
+        slot.shownEvents.clear()
+      }
+    }
+  }
+
+  const offSyncRequest = deps.summarySync.onForwardedSessionIds(handleForwardedBatch)
+  const offPool = deps.watchPool(() => {
+    try {
+      scanSlots()
+    } catch (error) {
+      log?.('client events merge pool rescan failed: %s', messageOf(error))
+    } finally {
+      flushWaiters()
+    }
+  })
+
+  const onExternalAbort = (): void => {
+    alive = false
+    for (const slot of [...slots.values()]) slot.controller?.abort()
+    flushWaiters()
+    channel.end()
+  }
+  if (signal !== undefined) signal.addEventListener('abort', onExternalAbort)
+
+  scanSlots()
+
+  const localIterator = local[Symbol.asyncIterator]()
+  const pumpLocal = async (): Promise<void> => {
+    try {
+      while (alive) {
+        const result = await localIterator.next()
+        if (result.done === true) break
+        channel.push(result.value)
+        if (!localOpened) {
+          localOpened = true
+          if (deferredRefresh) {
+            deferredRefresh = false
+            channel.push(catalogRefreshFrame())
+          }
+          const pendingBatch = deps.summarySync.consumePendingRequest()
+          if (deferredSummarySync || pendingBatch.length > 0) {
+            deferredSummarySync = false
+            runSummarySync(pendingBatch)
+          }
+          for (const slot of [...slots.values()]) {
+            if (slot.statusDeferred) {
+              slot.statusDeferred = false
+              runStatusSync(slot)
+            }
+          }
+        }
+      }
+    } catch (error) {
+      if (alive) channel.fail(error)
+      return
+    }
+    if (!alive) return
+    alive = false
+    for (const slot of [...slots.values()]) slot.controller?.abort()
+    flushWaiters()
+    channel.end()
+  }
+
+  void pumpLocal()
+  try {
+    while (true) {
+      const result = await channel.next()
+      if (result.done === true) break
+      yield result.value
+    }
+  } finally {
+    alive = false
+    if (retryTimer !== undefined) clock.clearTimeout(retryTimer)
+    offSyncRequest()
+    offPool()
+    if (signal !== undefined) signal.removeEventListener('abort', onExternalAbort)
+    for (const slot of [...slots.values()]) {
+      slot.removed = true
+      slot.offState()
+      slot.controller?.abort()
+    }
+    slots.clear()
+    flushWaiters()
+    void Promise.resolve(localIterator.return?.(undefined)).catch(() => {})
+  }
+}
+
+/**
+ * Install the two own-property wrappers on the raw gateway. Assumes
+ * {@link checkGatewayShape} passed (the wiring gates on it) — this function
+ * records the verdict but does not re-gate, so it stays usable in tests
+ * that install over deliberately odd shapes.
+ */
+/**
+ * P55-2: whether `filePath` lives at or under `cwd` — the /api/file
+ * attribution test. Both paths are compared backslash-folded to `/` (a
+ * server-Windows cwd meets a server-Windows image path, and the Markdown
+ * renderer may hand either separator over), trailing separators of `cwd`
+ * are dropped, and the match is exact-or-subpath (`cwd + '/'` prefix — a
+ * directory merely PREFIXED by the cwd string is not a match). Windows
+ * drive-rooted pairs compare case-insensitively WHOLE (`C:\Users` vs
+ * `c:\users` — the drive letter is the visible case hazard, but NTFS is
+ * case-insensitive end to end, and a missed match costs a permanently
+ * broken image while an over-match needs two same-server cwds differing
+ * only by case); everything else stays case-sensitive (POSIX is).
+ * Deliberately NOT node:path — the two ends may run on different platforms,
+ * so the rule is pure string arithmetic over the server's paths.
+ */
+export function pathMatchesCwd(filePath: string, cwd: string): boolean {
+  const slashify = (value: string): string => value.replaceAll('\\', '/')
+  const file = slashify(filePath)
+  let root = slashify(cwd)
+  while (root.length > 1 && root.endsWith('/')) root = root.slice(0, -1)
+  if (root === '') return false
+  const matches = (f: string, r: string): boolean => f === r || f.startsWith(`${r}/`)
+  if (matches(file, root)) return true
+  if (/^[a-z]:/i.test(root) && /^[a-z]:/i.test(file)) return matches(file.toLowerCase(), root.toLowerCase())
+  return false
+}
+
+export function installIntercept(options: InstallInterceptOptions): InterceptHandle {
+  const { raw, log } = options
+  const clock = options.clock ?? defaultClock
+  // MS-3: exactly one mode — the pool when given, the single row client
+  // otherwise. Installing with neither is a wiring bug; refuse loudly at
+  // install instead of crashing on the first remote call.
+  const pool = options.pool
+  const relay = options.relay
+  const getServerId = options.getServerId
+  if (pool === undefined && (relay === undefined || getServerId === undefined)) {
+    throw new Error('installIntercept requires either `relay` + `getServerId` (single server) or `pool`')
+  }
+  // The single-server facts, proven present by the check above. The
+  // single-server code paths read THESE (never the optional originals), so
+  // the old behavior stays byte-identical without a narrowing dance.
+  const singleRelay = relay as RelayClient
+  const singleGetServerId = getServerId as () => string | undefined
+  // T63: the summary-sync hub shared by the merged streams — the workspace
+  // route nudges, the events leg fetches-and-announces. One per install: it
+  // outlives individual stream generations so a nudge from a workspace leg
+  // reaches whichever $events generation is open.
+  const summarySync = createSessionSummarySync()
+  // PB-25b: the inventory slot factory (the wiring's union feed) — passed
+  // down to every merged stream, which owns one slot for its lifetime.
+  const createSessionInventorySlot = options.createSessionInventorySlot
+  // MS-3: the pool-event hub behind handle.notePoolEvent() — the wiring
+  // forwards the pool's onStateChange/onServerRemoved callbacks here, and
+  // every live merged stream (plus the pool-mode catalog watcher below)
+  // re-scans on the broadcast.
+  const poolListeners = new Set<() => void>()
+  const watchPool = (fn: () => void): (() => void) => {
+    poolListeners.add(fn)
+    return () => {
+      poolListeners.delete(fn)
+    }
+  }
+  // T62: the current-session getter and the live-merged-stream listener
+  // registry behind handle.currentSessionChanged().
+  const getCurrentSession = options.getCurrentSession ?? (() => ({ kind: 'unavailable' }) as const)
+  const currentSessionListeners = new Set<() => void>()
+  const watchCurrentSession = (fn: () => void): (() => void) => {
+    currentSessionListeners.add(fn)
+    return () => { currentSessionListeners.delete(fn) }
+  }
+  const uninstallListeners = new Set<() => void>()
+  const watchUninstall = (fn: () => void): (() => void) => {
+    uninstallListeners.add(fn)
+    return () => { uninstallListeners.delete(fn) }
+  }
+  const gateway = raw as Record<string | symbol, unknown>
+  const shape = checkGatewayShape(raw)
+  const counters = { openWireStream: 0, dispatchRpc: 0 }
+  const failures: InterceptFailureRecord[] = []
+  const incompatible: IncompatibleCallRecord[] = []
+  // The closed-session registry (T34): insertion-ordered, capped, virtual-id
+  // keyed. Entries live until THEIR session proves reachable again (a
+  // succeeding call for it) — a reconnect clears nothing (T34-fix): a link
+  // that flapped under a still-standing closure would make the banner flicker
+  // away and back.
+  const closedSessions = new Map<string, ClosedSessionRecord['reason']>()
+  // T73-fix: waiters for "a closed-session record was just cleared" — the
+  // quiet session/follow hold (rewriteUpstream) ends its silence the moment
+  // the session it holds for is served again, so a re-enabled remote comes
+  // back with a fresh history instead of staying blind under its banner.
+  const closedClearWaiters = new Set<() => void>()
+  // P55-2: the /api/file attribution state. `remoteSessionCwds` maps each
+  // remote session's VIRTUAL id to its cwd as last seen (snapshot header,
+  // session/list rows); `activeRemoteFollows` holds every live remote
+  // `session/follow` this process opened (symbol-keyed so concurrent pages
+  // each hold their own); `lastFollowedSession` is the follow the wrapper
+  // answered MOST RECENTLY, local or remote — together they resolve a
+  // path-only image request to its owning session without waiting for the
+  // browser's 1s current-session report. All in-memory, session-scale
+  // (the cwd map is capped like the closed-session registry). The
+  // `session/control` merge is deliberately NOT a source: its frame
+  // vocabulary (RT dsh-api-session-controller lib/typert.remote-client.js —
+  // `baseline` with value.projections, `projection` with sessionId/seq/
+  // changes) carries no session summary and no cwd, so a scan there could
+  // never record anything.
+  type RemoteSessionCwd = { serverId: string; sessionId: string; cwd: string }
+  const remoteSessionCwds = new Map<string, RemoteSessionCwd>()
+  const activeRemoteFollows = new Map<symbol, { serverId: string; sessionId: string }>()
+  let lastFollowedSession: { kind: 'remote'; serverId: string; sessionId: string } | { kind: 'local' } | undefined
+  const MAX_REMOTE_SESSION_CWDS = 200
+  const recordRemoteSessionCwd = (serverId: string, rawSessionId: unknown, cwd: unknown): void => {
+    if (typeof rawSessionId !== 'string' || rawSessionId === '') return
+    if (typeof cwd !== 'string' || cwd === '') return
+    const key = toVirtual(serverId, rawSessionId)
+    // Re-insert to refresh the recency order, then cap like `closedSessions`.
+    remoteSessionCwds.delete(key)
+    if (remoteSessionCwds.size >= MAX_REMOTE_SESSION_CWDS) {
+      const oldest = remoteSessionCwds.keys().next()
+      if (oldest.done !== true) remoteSessionCwds.delete(oldest.value)
+    }
+    remoteSessionCwds.set(key, { serverId, sessionId: rawSessionId, cwd })
+  }
+  /** Record every cwd a remote `session/list` result carries (both merge
+   * modes call this on the RAW remote value, before ids go virtual). */
+  const noteRemoteSessionListCwds = (remoteResult: unknown, serverId: string): void => {
+    if (!isPlainObject(remoteResult) || !Array.isArray(remoteResult.items)) return
+    for (const item of remoteResult.items) {
+      if (!isPlainObject(item)) continue
+      const id = typeof item.sessionId === 'string' && item.sessionId !== ''
+        ? item.sessionId
+        : typeof item.id === 'string' && item.id !== ''
+          ? item.id
+          : undefined
+      if (id === undefined) continue
+      recordRemoteSessionCwd(serverId, id, item.cwd)
+    }
+  }
+  /**
+   * The resolution the /api/file wrap buys with one call. Steps, in order:
+   * A) the ACTIVE remote session — the browser-reported current session
+   * (unless this process's newest follow went LOCAL, which is the newer
+   * fact), else the newest follow, else the newest live remote follow;
+   * B) a precise cwd match — the active session's own cwd first, then any
+   * known cwd the path falls under (a session with a LIVE follow preferred,
+   * else the most recently refreshed match);
+   * C) no cwd claim anywhere → the active remote (so a just-opened page's
+   * first image resolves with zero cwd knowledge), or `undefined` when no
+   * remote session is active — a local session's images stay local.
+   */
+  const resolveRemoteFileScope = (rawPath: string): { serverId: string; sessionId: string } | undefined => {
+    if (typeof rawPath !== 'string' || rawPath === '') return undefined
+    let activeRemote: { serverId: string; sessionId: string } | undefined
+    const current = getCurrentSession()
+    if (current.kind === 'open') {
+      const parts = fromVirtual(current.sessionId)
+      if (parts !== undefined && lastFollowedSession?.kind !== 'local') {
+        activeRemote = { serverId: parts.serverId, sessionId: parts.id }
+      }
+    }
+    if (activeRemote === undefined && lastFollowedSession?.kind === 'remote') {
+      activeRemote = { serverId: lastFollowedSession.serverId, sessionId: lastFollowedSession.sessionId }
+    }
+    if (activeRemote === undefined && activeRemoteFollows.size > 0) {
+      const values = [...activeRemoteFollows.values()]
+      const last = values[values.length - 1]
+      if (last !== undefined) activeRemote = { ...last }
+    }
+    if (activeRemote !== undefined) {
+      const own = remoteSessionCwds.get(toVirtual(activeRemote.serverId, activeRemote.sessionId))
+      if (own !== undefined && pathMatchesCwd(rawPath, own.cwd)) {
+        return { serverId: own.serverId, sessionId: own.sessionId }
+      }
+    }
+    const followedVirtuals = new Set([...activeRemoteFollows.values()].map((entry) => toVirtual(entry.serverId, entry.sessionId)))
+    let latestMatch: RemoteSessionCwd | undefined
+    let followedMatch: RemoteSessionCwd | undefined
+    for (const entry of remoteSessionCwds.values()) {
+      if (!pathMatchesCwd(rawPath, entry.cwd)) continue
+      latestMatch = entry
+      if (followedVirtuals.has(toVirtual(entry.serverId, entry.sessionId))) followedMatch = entry
+    }
+    if (followedMatch !== undefined) return { serverId: followedMatch.serverId, sessionId: followedMatch.sessionId }
+    if (latestMatch !== undefined) return { serverId: latestMatch.serverId, sessionId: latestMatch.sessionId }
+    return activeRemote
+  }
+  // The last successfully fetched SERVER model catalog (T52-fix), kept for
+  // the offline merges of the `session/modelCatalog` route below — cleared
+  // on a pairing wall (eagerly, by the T52-fix2 catalog watcher; the route's
+  // own drop is the backstop) and never served for another server's id (see the
+  // route's doc). Only an in-memory value: the groups are display data and
+  // a reload refetches them anyway. Since T52-fix3 it feeds ONLY this route:
+  // the modelSelection provider rewrites are unconditional again (the host's
+  // projection store is first-write-wins per seq, so a catalog-gated rewrite
+  // would poison the store — see virtualizeModelSelectionValue), and the
+  // `groups` membership set is gone with the gate.
+  let serverCatalogCache: { identity: MergerIdentity; value: unknown } | undefined
+  /**
+   * The serving generation, bumped on every pairing wall (`unpaired` /
+   * `revoked`, T52-fix3): a catalog fetch that was IN FLIGHT when the wall
+   * rose must not write its answer back — the wall's groups must not outlive
+   * it, and a late write would resurrect them under the offline merge below.
+   * Both cache writes (the proactive fetch here, the route's own fetch)
+   * snapshot the counter before invoking and compare before storing; a
+   * mismatched answer is silently dropped — it is not a fault, the next
+   * serving period fetches fresh anyway.
+   */
+  let catalogGeneration = 0
+  const rememberServerCatalog = (identity: MergerIdentity, value: unknown, generation: number): void => {
+    if (generation !== catalogGeneration) return
+    serverCatalogCache = { identity, value }
+  }
+  /** MS-3 pool mode: the per-server form of the same cache — one entry per
+   * known `serverId`, keyed by it. An offline entry keeps serving its cache
+   * (the groups must not go blank mid-outage); an entry that LEAVES the pool
+   * takes its cache with it (its groups must not outlive the pairing). */
+  const serverCatalogCaches = new Map<string, { identity: MergerIdentity; value: unknown }>()
+  const catalogGenerations = new Map<string, number>()
+  /** One server-catalog fetch whose answer only feeds the cache (T52-fix2):
+   * the proactive pull that runs as soon as the relay serves — and once at
+   * install when the relay already serves (subscribe replays no state —
+   * relay-client.ts setState returns on a same-state write — so the
+   * subscription alone would miss an install-into-online). Failures are
+   * diagnostics-ring entries, nothing else (the route's own fetch is the
+   * user-visible path and answers local-only there). */
+  const fetchServerCatalog = (identity: MergerIdentity): void => {
+    const generation = catalogGeneration
+    void singleRelay.invoke('session', 'modelCatalog', {}, undefined).then(
+      (value) => {
+        rememberServerCatalog(identity, value, generation)
+      },
+      (error: unknown) => {
+        recordFailure('session/modelCatalog', error instanceof RelayError ? error.code : 'internal')
+      },
+    )
+  }
+  /** MS-3 pool mode: the per-server proactive fetch. The identity's display
+   * name is the POOL's (the `-1`/`-2` disambiguated one) — it titles the
+   * merged catalog's virtual groups. Generation-guarded per server, like
+   * the single-server fetch above. */
+  const fetchServerCatalogFor = (entry: { serverId: string; displayName: string; client: RelayClient }): void => {
+    const serverId = entry.serverId
+    const generation = catalogGenerations.get(serverId) ?? 0
+    void entry.client.invoke('session', 'modelCatalog', {}, undefined).then(
+      (value) => {
+        if ((catalogGenerations.get(serverId) ?? 0) !== generation) return
+        serverCatalogCaches.set(serverId, { identity: { serverId, serverName: entry.displayName }, value })
+      },
+      (error: unknown) => {
+        recordFailure('session/modelCatalog', error instanceof RelayError ? error.code : 'internal')
+      },
+    )
+  }
+  // The catalog watcher (T52-fix2). The subscription fires on the real
+  // online transitions (first handshake, every recovery) — and since T59
+  // also on name-only notifications, which arrive with the state still
+  // `online` and are deduped by the same refreshKey/stateSeen gates above.
+  // The install-time check below covers an install into an already-online
+  // relay. `unpaired` / `revoked`
+  // drop the cache the same way the catalog route does lazily — the wall's
+  // groups must not outlive it — and bump the generation so an in-flight
+  // fetch cannot write the old catalog back (T52-fix3). Faults stay
+  // contained: the sync body cannot throw, and the fetch settles through
+  // .then/.catch above.
+  let offCatalogWatch: (() => void) | undefined
+  // MS-3 pool mode: one client subscription per pool entry (the map below),
+  // created and retired by the watchPool rescan. MS-5: uninstall tears them
+  // ALL down — `offCatalogWatch` only unsubscribes the rescan itself, and a
+  // left-behind per-entry subscription would keep firing into this dead
+  // generation's caches on every later state change.
+  const catalogWatched = new Map<string, () => void>()
+  if (pool === undefined) {
+    try {
+      offCatalogWatch = singleRelay.subscribe((state) => {
+        if (state === 'unpaired' || state === 'revoked') {
+          catalogGeneration += 1
+          serverCatalogCache = undefined
+          return
+        }
+        if (state !== 'online') return
+        const identity = relayIdentityOf(singleRelay)
+        if (identity !== undefined) fetchServerCatalog(identity)
+      })
+      // Install into an already-serving relay: subscribe replayed nothing, so
+      // the transition-based fetch would wait for the NEXT flap — fill the
+      // cache now instead (T52-fix3).
+      if (singleRelay.state === 'online') {
+        const identity = relayIdentityOf(singleRelay)
+        if (identity !== undefined) fetchServerCatalog(identity)
+      }
+    } catch (error) {
+      // Subscription failed: the cache still fills whenever the UI opens a
+      // dropdown (the route's own fetch), only later.
+      log?.('client catalog watcher unavailable: %s', messageOf(error))
+    }
+  } else {
+    // MS-3 pool mode: one watcher per entry, rescanned on every pool event.
+    // `unpaired` / `revoked` drop THAT server's cache and bump its
+    // generation; `online` proactively refetches it (an entry appearing
+    // already online is fetched at attach, same as the single-server
+    // install-into-online above).
+    offCatalogWatch = watchPool(() => {
+      const seen = new Set<string>()
+      for (const entry of pool.entries()) {
+        seen.add(entry.entryId)
+        if (catalogWatched.has(entry.entryId)) continue
+        const unsubscribe = entry.client.subscribe((state) => {
+          // The entry's serverId is read LIVE — a re-handshake may have
+          // renamed it since this listener attached.
+          const live = pool.entries().find((candidate) => candidate.entryId === entry.entryId)
+          const serverId = live?.serverId
+          if (serverId === undefined) return
+          if (state === 'unpaired' || state === 'revoked') {
+            catalogGenerations.set(serverId, (catalogGenerations.get(serverId) ?? 0) + 1)
+            serverCatalogCaches.delete(serverId)
+            return
+          }
+          if (state !== 'online') return
+          const current = live ?? entry
+          if (current.serverId !== undefined) {
+            fetchServerCatalogFor({ serverId: current.serverId, displayName: current.displayName, client: current.client })
+          }
+        })
+        catalogWatched.set(entry.entryId, unsubscribe)
+        if (entry.client.state === 'online' && entry.serverId !== undefined) {
+          fetchServerCatalogFor({ serverId: entry.serverId, displayName: entry.displayName, client: entry.client })
+        }
+      }
+      for (const [entryId, unsubscribe] of [...catalogWatched]) {
+        if (!seen.has(entryId)) {
+          unsubscribe()
+          catalogWatched.delete(entryId)
+        }
+      }
+    })
+    // Run the initial scan through the hub so the same rescan logic runs.
+    for (const listener of [...poolListeners]) listener()
+  }
+  const registerClosed = (sessionId: string, reason: ClosedSessionRecord['reason']): void => {
+    closedSessions.delete(sessionId)
+    if (closedSessions.size >= MAX_CLOSED_SESSIONS) {
+      const oldest = closedSessions.keys().next()
+      if (oldest.done !== true) closedSessions.delete(oldest.value)
+    }
+    closedSessions.set(sessionId, reason)
+  }
+  const clearClosed = (virtuals: VirtualParts[]): void => {
+    let cleared = false
+    for (const parts of virtuals) {
+      if (closedSessions.delete(toVirtual(parts.serverId, parts.id))) cleared = true
+    }
+    if (cleared) for (const waiter of [...closedClearWaiters]) waiter()
+  }
+  let installed = true
+  let selfCheck: SelfCheckResult | undefined
+
+  /**
+   * Reload overlay, for the record (CP4): the theoretical hazard is installing
+   * a NEW wrapper while an OLD one is still installed, so each captures the
+   * other and the older survives as a live layer. Cordis `fiber.restart()`
+   * disposes the old fiber FIRST (its effect calls {@link InterceptHandle.uninstall},
+   * restoring the saved property) and only then applies the new row — the
+   * overlay ordering never happens today, so there is nothing to absorb at
+   * install time. Detection is also not cheaply implementable: a reloaded row
+   * loads a FRESH module instance, so a stale wrapper shares no mark with the
+   * new one — telling "ours, from a dead generation" apart from another
+   * plugin's wrapper would take a process-wide registry, which the comment
+   * above argues is not worth it while the ordering cannot occur. The
+   * `installed === false → inert passthrough` rule below is the safety net
+   * for the ordering that CAN happen: a later plugin wrapping OVER us and
+   * keeping a reference past our uninstall.
+   *
+   * Save the CURRENT value per property (possibly another plugin's wrapper —
+   * shape note "own-property"), falling back to the prototype method only
+   * when the current value is not callable. Uninstall restores the saved
+   * own state verbatim: value if there was one, absence if not.
+   */
+  const saved: Record<string, { existed: boolean; value: unknown }> = {}
+  const chainTarget: Record<string, unknown> = {}
+  for (const name of ['openWireStream', 'dispatchRpc']) {
+    const existed = Object.prototype.hasOwnProperty.call(gateway, name)
+    const value = existed ? gateway[name] : undefined
+    saved[name] = { existed, value }
+    chainTarget[name] = typeof value === 'function' ? value : Object.getPrototypeOf(raw)?.[name]
+  }
+  // Filled in below, once the wrapper functions exist: uninstall may only
+  // touch a property that still holds OUR wrapper.
+  const wrappers: Record<string, unknown> = {}
+
+  const recordFailure = (endpoint: string, code: string): void => {
+    if (failures.length >= MAX_FAILURES) failures.shift()
+    failures.push({ time: new Date().toISOString(), endpoint, code })
+    // T42: validation-shaped refusals additionally land in the incompatible
+    // ring — every remote failure funnels through this one function, so the
+    // classification cannot drift between the invoke and stream routes.
+    if (!INCOMPATIBLE_CALL_CODES.has(code)) return
+    if (incompatible.length >= MAX_INCOMPATIBLE_CALLS) incompatible.shift()
+    incompatible.push({ time: Date.now(), endpoint, code })
+  }
+
+  const failEnvelope = (
+    endpoint: string,
+    code: string,
+    text: string,
+  ): { ok: false; error: { code: string; message: string; details: Record<string, unknown> } } => {
+    recordFailure(endpoint, code)
+    // `details: {}` is load-bearing: the UI's server-response parser throws
+    // `invalid server-response failure` on a details-less error (and the
+    // gateway's rpcErrorSchema demands the same shape).
+    return { ok: false, error: { code, message: text, details: {} } }
+  }
+
+  /**
+   * The shared validation both routes apply before forwarding — now (MS-3)
+   * resolving the TARGET SERVER as well as the call's shape. The single
+   * `relay` mode keeps the original verdict order byte-for-byte (offline →
+   * mismatch → unsupported); pool mode routes by the virtual id's serverId:
+   * no handshook server in the pool answers `remote-offline`, a handshook
+   * pool without the target server answers `remote-mismatch`, and the
+   * matched entry's client is the forwarding leg. A refusal is recorded
+   * once, here, by the caller passing it through {@link failEnvelope}.
+   */
+  const copy = () => INTERCEPT_COPY[resolveInterceptLang(options.lang)]
+  type Verdict = { ok: true; client: RelayClient; serverId: string } | { ok: false; code: string; message: string }
+  function validate(endpoint: string, virtuals: VirtualParts[]): Verdict {
+    const first = virtuals[0].serverId
+    const c = copy()
+    if (pool === undefined) {
+      const current = singleGetServerId()
+      if (current === undefined) return { ok: false, code: 'remote-offline', message: c.notConnected }
+      if (virtuals.some((parts) => parts.serverId !== first) || current !== first) {
+        return { ok: false, code: 'remote-mismatch', message: c.mismatch }
+      }
+      if (CLIENT_METHOD_FIELDS[endpoint] === undefined) {
+        return { ok: false, code: 'remote-unsupported', message: c.unsupported }
+      }
+      return { ok: true, client: singleRelay, serverId: first }
+    }
+    if (virtuals.some((parts) => parts.serverId !== first)) {
+      return { ok: false, code: 'remote-mismatch', message: c.mismatch }
+    }
+    const known = pool.entries().filter((entry) => entry.serverId !== undefined)
+    if (known.length === 0) return { ok: false, code: 'remote-offline', message: c.notConnected }
+    const target = known.find((entry) => entry.serverId === first)
+    if (target === undefined) return { ok: false, code: 'remote-mismatch', message: c.mismatch }
+    if (CLIENT_METHOD_FIELDS[endpoint] === undefined) {
+      return { ok: false, code: 'remote-unsupported', message: c.unsupported }
+    }
+    return { ok: true, client: target.client, serverId: first }
+  }
+
+  /**
+   * The T32 `$events/result` split: an answer whose eventId is VIRTUAL
+   * belongs to a forwarded remote event and must NOT reach the local
+   * gateway (its own `$events` never delivered it — the local dispatcher
+   * would answer with its `no active event stream` failure). The virtual
+   * id goes back to the original, the local payload's clientId (the local
+   * stream's own) is discarded — the relay server composes the gateway
+   * payload from ITS subscription's clientId — and the outcome rides
+   * verbatim. Anything else, including a malformed payload, is the local
+   * gateway's business.
+   */
+  function forwardEventResult(payload: unknown, signal: AbortSignal | undefined, peer: unknown): unknown {
+    const args = argsOf(payload)
     const eventId = isPlainObject(args) ? args.eventId : undefined
     const virtual = fromVirtual(eventId)
     if (virtual === undefined) {
@@ -2742,7 +4097,18 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
       )
     }
     const endpoint = '$events/result'
-    const current = getServerId()
+    const route = ((): { client: RelayClient } | 'offline' | 'missing' | 'mismatch' => {
+      if (pool === undefined) {
+        const current = singleGetServerId()
+        if (current === undefined || singleRelay.state !== 'online') return 'offline'
+        if (virtual.serverId !== current) return 'mismatch'
+        return { client: singleRelay }
+      }
+      const target = pool.getByServerId(virtual.serverId)
+      if (target === undefined) return 'missing'
+      if (target.client.state !== 'online') return 'offline'
+      return { client: target.client }
+    })()
     // Offline (T34-fix): a refusal envelope would RESTART the UI's whole
     // `$events` generation — the client face's answer() throws on a
     // `!response.ok` body and the pump treats that as a delivery failure
@@ -2751,15 +4117,25 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
     // synthesized cancels the dying leg already sent have closed these
     // prompts anyway. Answer the silent ok DSH itself gives a stale result,
     // and record the refusal in the diagnostics ring instead — the
-    // non-online write-refusal message, so the banner's word matches.
-    if (current === undefined || relay.state !== 'online') {
-      failEnvelope(endpoint, 'remote-offline', WRITE_OFFLINE_MESSAGE)
+    // non-online write-refusal message, so the banner's word matches. In
+    // pool mode a leg the pool no longer serves (`missing` — unpaired away,
+    // deduped, never paired) reads the same way: nothing can settle those
+    // events anymore, so the silent ok wins there too. The single-server
+    // mismatch keeps its original REFUSAL envelope (wrong server is a
+    // different fact from a leg that just left).
+    if (route === 'offline') {
+      failEnvelope(endpoint, 'remote-offline', copy().writeOffline)
+      return { ok: true, value: undefined }
+    }
+    if (route === 'missing') {
+      failEnvelope(endpoint, 'remote-mismatch', copy().mismatch)
       return { ok: true, value: undefined }
     }
-    if (virtual.serverId !== current) return failEnvelope(endpoint, 'remote-mismatch', '此远程会话属于其他主服务端')
+    if (route === 'mismatch') return failEnvelope(endpoint, 'remote-mismatch', copy().mismatch)
+    const client = route.client
     return (async (): Promise<DispatchEnvelope> => {
       try {
-        await relay.postEventResult(virtual.id, isPlainObject(args) ? args.outcome : undefined, signal)
+        await client.postEventResult(virtual.id, isPlainObject(args) ? args.outcome : undefined, signal)
         return { ok: true, value: undefined }
       } catch (error) {
         const code = error instanceof RelayError ? error.code : 'internal'
@@ -2802,11 +4178,13 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
     // A WRITE while the relay is not serving (T34, whitelist rule per
     // T34-fix): refused here, never sent — the call could only fail out
     // there, and the read paths answer for themselves (forwarded as today,
-    // failing with their own transport error).
-    if (isRemoteWrite(endpoint) && relay.state !== 'online') {
-      return failEnvelope(endpoint, 'remote-offline', WRITE_OFFLINE_MESSAGE)
+    // failing with their own transport error). Pool mode (MS-3): the verdict
+    // names the TARGET leg — its state is the one that counts.
+    if (isRemoteWrite(endpoint) && verdict.client.state !== 'online') {
+      return failEnvelope(endpoint, 'remote-offline', copy().writeOffline)
     }
     const serverId = verdict.serverId
+    const client = verdict.client
     const slash = endpoint.indexOf('/')
     const namespace = slash === -1 ? endpoint : endpoint.slice(0, slash)
     const method = slash === -1 ? '' : endpoint.slice(slash + 1)
@@ -2832,9 +4210,9 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
       const references = restoreSessionReferences(clone, namespace, method, serverId)
       clone = references.args
       if (!references.ok) {
-        return failEnvelope(endpoint, 'remote-unsupported', '引用的会话不在服务端上，无法转发')
+        return failEnvelope(endpoint, 'remote-unsupported', copy().referenceNotOnServer)
       }
-      const value = await relay.invoke(namespace, method, clone, signal)
+      const value = await client.invoke(namespace, method, clone, signal)
       // The session answered: any closed-session entry for it is stale
       // (re-shared and served again) — the banner may go.
       clearClosed(virtuals)
@@ -2863,7 +4241,7 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
       recordFailure(endpoint, code)
       // A call on a closed session reads like the banner, not like the
       // relay's bare code (T73).
-      const message = code === 'not-shared' ? CLOSED_MESSAGE : messageOf(error)
+      const message = code === 'not-shared' ? copy().closed : messageOf(error)
       return { ok: false, error: { code, message, details: error instanceof RelayError && isPlainObject(error.details) ? error.details : {} } }
     }
   }
@@ -2897,20 +4275,20 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
    * can never reach us (subscribe's contract keeps listener faults contained
    * on the client side).
    */
-  function waitForOnline(signal: AbortSignal | undefined): Promise<ServeWait> {
+  function waitForOnline(client: RelayClient, signal: AbortSignal | undefined): Promise<ServeWait> {
     return new Promise<ServeWait>((resolve) => {
       if (signal?.aborted === true) {
         resolve('aborted')
         return
       }
-      if (relay.state === 'online') {
+      if (client.state === 'online') {
         resolve('online')
         return
       }
       // The wall may already be down when the wait starts (the leg died and
       // the state flipped before this call) — same verdict as below.
-      if (relay.state === 'revoked' || relay.state === 'unpaired') {
-        resolve(relay.state)
+      if (client.state === 'revoked' || client.state === 'unpaired') {
+        resolve(client.state)
         return
       }
       let off: (() => void) | undefined
@@ -2922,7 +4300,7 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
         resolve(verdict)
       }
       const onAbort = (): void => settle('aborted')
-      off = relay.subscribe((state) => {
+      off = client.subscribe((state) => {
         if (state === 'online') settle('online')
         else if (state === 'revoked' || state === 'unpaired') settle(state)
       })
@@ -2955,14 +4333,14 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
    * current backoff step. `aborted` only on caller abort; `revoked` /
    * `unpaired` when the pairing wall came down (CP5).
    */
-  async function waitServeAgain(signal: AbortSignal | undefined, backoffMs: number): Promise<ServeWait> {
-    if (relay.state === 'online') {
+  async function waitServeAgain(client: RelayClient, signal: AbortSignal | undefined, backoffMs: number): Promise<ServeWait> {
+    if (client.state === 'online') {
       await delayWait(signal, backoffMs)
       if (signal?.aborted === true) return 'aborted'
-      if (relay.state !== 'online') return waitForOnline(signal)
+      if (client.state !== 'online') return waitForOnline(client, signal)
       return 'online'
     }
-    return waitForOnline(signal)
+    return waitForOnline(client, signal)
   }
 
   /**
@@ -3007,6 +4385,7 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
    */
   async function* rewriteUpstream(
     endpoint: string,
+    client: RelayClient,
     upstream: AsyncIterable<unknown>,
     serverId: string,
     claimed: VirtualParts[],
@@ -3033,6 +4412,12 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
             // closed-session entry for it is stale (T34).
             clearClosed(claimed)
           }
+          // P55-2: the snapshot's header carries the session identity and its
+          // cwd in ORIGINAL ids — record before the rewrite below virtualizes
+          // them, so /api/file can attribute the session's own image paths.
+          if (endpoint === 'session/follow' && isPlainObject(frame) && frame.type === 'snapshot' && isPlainObject(frame.header)) {
+            recordRemoteSessionCwd(serverId, frame.header.id, frame.header.cwd)
+          }
           yield rewriteFrame(endpoint, frame, serverId)
         }
         return
@@ -3090,7 +4475,7 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
             if (onCleared !== undefined) closedClearWaiters.delete(onCleared)
             return
           }
-          throw new CodedStreamError(code, CLOSED_MESSAGE)
+          throw new CodedStreamError(code, copy().closed)
         }
         recordFailure(endpoint, code)
         // A link-down fact (CP4), scoped by CP5: only the carrier-retry
@@ -3103,7 +4488,7 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
         if (!SESSION_STREAM_HOLD_ENDPOINTS.has(endpoint)) {
           throw new CodedStreamError(code, messageOf(error))
         }
-        const serve = await waitServeAgain(signal, reopenDelayMs)
+        const serve = await waitServeAgain(client, signal, reopenDelayMs)
         if (serve === 'aborted') return
         // The pairing wall came down while held (CP5): no ladder climbs back
         // from `revoked`/`unpaired` — only the settings page can — so the
@@ -3112,9 +4497,10 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
         // would freeze the panel with no verdict and no wake-up.
         if (serve !== 'online') {
           recordFailure(endpoint, serve)
+          const c = copy()
           throw new CodedStreamError(
             serve,
-            serve === 'revoked' ? '配对令牌已被吊销，请在设置页重新配对' : '尚未与服务端配对，请在设置页完成配对',
+            serve === 'revoked' ? c.revoked : c.unpaired,
           )
         }
         if (callerAborted()) return
@@ -3131,6 +4517,11 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
    * virtualized session ids. Paged requests, an offline relay, a non-ok local
    * envelope and a failed remote call all answer the local result untouched —
    * only a remote failure is recorded.
+   *
+   * MS-3 pool mode: EVERY online server's first page is fetched
+   * concurrently and folded in `pool.entries()` order (pairing order), one
+   * `mergeSessionList` per server. A failing leg is recorded and skipped —
+   * the other servers' rows still merge.
    */
   async function mergedSessionListCall(
     endpoint: string,
@@ -3151,10 +4542,35 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
     // Only the first page merges: a cursor pages the local list alone.
     const request = isPlainObject(args) ? args._request : undefined
     if (isPlainObject(request) && request.cursor !== undefined) return localEnvelope
-    const identity = relayIdentityOf(relay)
-    if (identity === undefined || relay.state !== 'online') return localEnvelope
+    if (pool !== undefined) {
+      const online = pool.entries().filter((entry) => entry.serverId !== undefined && entry.client.state === 'online')
+      if (online.length === 0) return localEnvelope
+      const settled = await Promise.all(
+        online.map((entry) =>
+          entry.client.invoke('session', 'list', isPlainObject(args) ? args : {}, signal).then(
+            (value) => ({ ok: true as const, value, serverId: entry.serverId as string }),
+            (error: unknown) => ({ ok: false as const, error, serverId: entry.serverId as string }),
+          ),
+        ),
+      )
+      let value = localEnvelope.value
+      for (const result of settled) {
+        if (!result.ok) {
+          recordFailure(endpoint, result.error instanceof RelayError ? result.error.code : 'internal')
+          continue
+        }
+        // P55-2: the RAW remote rows (original ids) feed the /api/file cwd
+        // registry before the merge virtualizes them.
+        noteRemoteSessionListCwds(result.value, result.serverId)
+        value = mergeSessionList(value, result.value, result.serverId)
+      }
+      return { ok: true, value }
+    }
+    const identity = relayIdentityOf(singleRelay)
+    if (identity === undefined || singleRelay.state !== 'online') return localEnvelope
     try {
-      const remote = await relay.invoke('session', 'list', isPlainObject(args) ? args : {}, signal)
+      const remote = await singleRelay.invoke('session', 'list', isPlainObject(args) ? args : {}, signal)
+      noteRemoteSessionListCwds(remote, identity.serverId)
       return { ok: true, value: mergeSessionList(localEnvelope.value, remote, identity.serverId) }
     } catch (error) {
       recordFailure(endpoint, error instanceof RelayError ? error.code : 'internal')
@@ -3197,8 +4613,52 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
     )) as unknown
     // A local failure is the answer — there is nothing to merge into.
     if (!isPlainObject(localEnvelope) || localEnvelope.ok !== true) return localEnvelope
-    const identity = relayIdentityOf(relay)
-    if (identity !== undefined && relay.state === 'online') {
+    if (pool !== undefined) {
+      // MS-3: every PAIRED server contributes its own groups, folded in
+      // pairing order; each server's last fetched catalog is cached by its
+      // serverId so an offline server keeps its groups while the online ones
+      // refetch. A cache whose server left the pool dies with the entry.
+      const entries = pool.entries().filter((entry) => entry.serverId !== undefined)
+      if (entries.length === 0) return localEnvelope
+      const online = entries.filter((entry) => entry.client.state === 'online')
+      const settled =
+        online.length === 0
+          ? []
+          : await Promise.all(
+              online.map((entry) =>
+                entry.client.invoke('session', 'modelCatalog', {}, signal).then(
+                  (value) => ({ ok: true as const, value, serverId: entry.serverId as string }),
+                  (error: unknown) => ({ ok: false as const, error, serverId: entry.serverId as string }),
+                ),
+              ),
+            )
+      const resultsByServer = new Map(settled.map((result) => [result.serverId, result]))
+      let acc = localEnvelope.value
+      for (const entry of entries) {
+        const serverId = entry.serverId as string
+        const identity: MergerIdentity = { serverId, serverName: entry.displayName }
+        const result = resultsByServer.get(serverId)
+        if (result === undefined) {
+          const cached = serverCatalogCaches.get(serverId)
+          if (cached !== undefined) acc = mergeModelCatalogs(acc, cached.value, cached.identity)
+          continue
+        }
+        if (!result.ok) {
+          recordFailure(endpoint, result.error instanceof RelayError ? result.error.code : 'internal')
+          const cached = serverCatalogCaches.get(serverId)
+          if (cached !== undefined) acc = mergeModelCatalogs(acc, cached.value, cached.identity)
+          continue
+        }
+        serverCatalogCaches.set(serverId, { identity, value: result.value })
+        acc = mergeModelCatalogs(acc, result.value, identity)
+      }
+      for (const serverId of [...serverCatalogCaches.keys()]) {
+        if (!entries.some((entry) => entry.serverId === serverId)) serverCatalogCaches.delete(serverId)
+      }
+      return { ok: true, value: acc }
+    }
+    const identity = relayIdentityOf(singleRelay)
+    if (identity !== undefined && singleRelay.state === 'online') {
       try {
         // The method has NO parameters (RT lib/typert.remote-client.js:1019) —
         // the relay route allows it field-less (relay-access.ts), filters the
@@ -3209,7 +4669,7 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
         // the counter and the answer never re-enters the cache — the caller
         // still gets its (live) answer, it asked while the link served.
         const generation = catalogGeneration
-        const remote = await relay.invoke('session', 'modelCatalog', {}, signal)
+        const remote = await singleRelay.invoke('session', 'modelCatalog', {}, signal)
         rememberServerCatalog(identity, remote, generation)
         return { ok: true, value: mergeModelCatalogs(localEnvelope.value, remote, identity) }
       } catch (error) {
@@ -3219,7 +4679,7 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
     }
     // Not serving normally. A pairing wall is a verdict about the server
     // itself — its groups must not outlive it.
-    if (relay.state === 'unpaired' || relay.state === 'revoked') {
+    if (singleRelay.state === 'unpaired' || singleRelay.state === 'revoked') {
       serverCatalogCache = undefined
       return localEnvelope
     }
@@ -3277,16 +4737,26 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
     const sessionParts = fromVirtual(sessionId)
     const providerParts = fromVirtual(provider)
     if (sessionParts === undefined && providerParts === undefined) return undefined
+    const c = copy()
     if (sessionParts === undefined) {
-      return { code: 'remote-unsupported', message: '该模型分组属于远程服务端，无法在本机会话中使用' }
+      return { code: 'remote-unsupported', message: c.modelGroupRemote }
     }
-    if (getServerId() !== sessionParts.serverId) return undefined
+    // MS-3: the session's server is looked up in the POOL (by the virtual
+    // id's serverId); a pool without that server falls through to the
+    // generic path's verdict (offline / mismatch). The message names the
+    // pool's display name — the same `-1`/`-2` disambiguated one the merged
+    // catalog groups are titled with.
+    const displayName = ((): string | undefined => {
+      if (pool !== undefined) return pool.getByServerId(sessionParts.serverId)?.displayName
+      if (singleGetServerId() !== sessionParts.serverId) return undefined
+      return relayIdentityOf(singleRelay)?.serverName
+    })()
+    if (displayName === undefined) return undefined
     if (providerParts === undefined) {
-      const serverName = relayIdentityOf(relay)?.serverName ?? '服务端'
-      return { code: 'remote-unsupported', message: `请选择「${serverName} · …」分组里的模型` }
+      return { code: 'remote-unsupported', message: c.modelGroupPickServer(displayName) }
     }
     if (providerParts.serverId !== sessionParts.serverId) {
-      return { code: 'remote-mismatch', message: '此模型分组属于其他主服务端' }
+      return { code: 'remote-mismatch', message: c.modelGroupMismatch }
     }
     return { args: { ...args, request: { ...request, provider: providerParts.id } } }
   }
@@ -3379,13 +4849,32 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
       return (async (): Promise<unknown> => {
         const local = await open.call(raw, endpoint, payload, uplink, peer, signal, control, uplinkWindow)
         if (!isAsyncIterable(local)) return local
-        return mergedEventsStream({ local, relay, signal, recordFailure, log, clock, summarySync })
+        if (pool !== undefined) {
+          return mergedEventsStreamMulti({ local, pool, signal, recordFailure, log, clock, summarySync, watchPool })
+        }
+        return mergedEventsStream({ local, relay: singleRelay, signal, recordFailure, log, clock, summarySync })
       })()
     }
     const args = argsOf(payload)
     const fields = CLIENT_METHOD_FIELDS[endpoint]
     const virtuals = collectVirtuals(fields, args)
     if (virtuals.length === 0) {
+      // P55-2: a LOCAL session/follow (a well-formed session address whose id
+      // is not virtual) is the newest fact about which page the user is on —
+      // recorded at the same instant the wrap is reached, so a later image
+      // request never resolves against the remote session just left.
+      if (endpoint === 'session/follow') {
+        const address = isPlainObject(args) && isPlainObject(args.request) ? args.request.address : undefined
+        if (
+          isPlainObject(address) &&
+          address.kind === 'session' &&
+          typeof address.sessionId === 'string' &&
+          address.sessionId !== '' &&
+          !isVirtual(address.sessionId)
+        ) {
+          lastFollowedSession = { kind: 'local' }
+        }
+      }
       if (endpoint === 'workspace/follow' || endpoint === 'session/control') {
         // The startup self-check probe wants the LOCAL baseline only — no
         // remote leg, no merge (its payload is registered in probePayloads).
@@ -3414,12 +4903,32 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
           // it); the remote leg carries no uplink.
           const local = await open.call(raw, endpoint, payload, uplink, peer, signal, control, uplinkWindow)
           if (!isAsyncIterable(local)) return local
+          if (pool !== undefined) {
+            return mergedGlobalStreamMulti({
+              endpoint,
+              namespace,
+              method,
+              local,
+              pool,
+              signal,
+              recordFailure,
+              log,
+              clock,
+              getCurrentSession,
+              watchCurrentSession,
+              watchUninstall,
+              summarySync,
+              createSessionInventorySlot,
+              watchPool,
+              lang: options.lang,
+            })
+          }
           return mergedGlobalStream({
             endpoint,
             namespace,
             method,
             local,
-            relay,
+            relay: singleRelay,
             signal,
             recordFailure,
             log,
@@ -3428,7 +4937,10 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
             watchCurrentSession,
             watchUninstall,
             summarySync,
-            createSessionInventorySlot,
+            lang: options.lang,
+            ...(createSessionInventorySlot !== undefined
+              ? { createSessionInventorySlot: () => createSessionInventorySlot(undefined) }
+              : {}),
           })
         })()
       }
@@ -3444,22 +4956,39 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
       )
     }
     const verdict = validate(endpoint, virtuals)
-    if (!verdict.ok) throwRecorded(endpoint, verdict.code, verdict.message)
+    if (!verdict.ok) {
+      // TA-2: a refusal must not leak the host's UplinkInbox — half-close it
+      // before the coded throw, the same courtesy the forwarded path's own
+      // failure paths extend below.
+      releaseUplink(uplink)
+      throwRecorded(endpoint, verdict.code, verdict.message)
+    }
     // A WRITE stream while the relay is not serving (CP4, the invoke route's
-    // T34 rule applied to the stream route): `terminal/follow` is the one
-    // write-shaped STREAM in the table — its attachment takes over the
-    // terminal's input control — so opening it into a dead link must refuse
-    // here, exactly like every other mutation.
-    if (isRemoteWrite(endpoint) && relay.state !== 'online') {
-      throwRecorded(endpoint, 'remote-offline', WRITE_OFFLINE_MESSAGE)
+    // T34 rule applied to the stream route): the write-shaped STREAMS of the
+    // table — `terminal/follow`, and its 0.2.2 duplex successor
+    // `terminal/attach` (REMOTE_UPLINK_STREAM_METHODS) — take over the
+    // terminal's input control, so opening them into a dead link must refuse
+    // here, exactly like every other mutation. MS-3: the TARGET leg's state
+    // is the one that counts.
+    if (isRemoteWrite(endpoint) && verdict.client.state !== 'online') {
+      releaseUplink(uplink)
+      throwRecorded(endpoint, 'remote-offline', copy().writeOffline)
     }
     // The multiplexed wire channel ALWAYS hands us an UplinkInbox here —
-    // never undefined. Remote streams consume no uplink items, so the uplink
-    // is half-closed and the stream forwarded (the host's own move for its
-    // `$events` subscription, gateway releaseUplink). Rejecting uplinks
-    // would reject every remote stream the UI opens.
-    releaseUplink(uplink)
+    // never undefined. One-directional remote streams consume no uplink
+    // items, so the uplink is half-closed and the stream forwarded (the
+    // host's own move for its `$events` subscription, gateway releaseUplink).
+    // TA-2: a DUPLEX member of REMOTE_UPLINK_STREAM_METHODS keeps its inbox —
+    // the host's TerminalInput write/resize commands ride it, so the iterable
+    // and the mux's uplink window (shape-checked, garbage dropped) travel to
+    // the relay client's pump instead; the pump releases the iterable itself
+    // when the stream ends. Rejecting uplinks would reject every remote
+    // stream the UI opens.
+    const forwardsUplink = REMOTE_UPLINK_STREAM_METHODS.has(endpoint) && isAsyncIterable(uplink)
+    if (!forwardsUplink) releaseUplink(uplink)
+    const normalizedWindow = forwardsUplink ? normalizeUplinkWindow(uplinkWindow) : undefined
     const serverId = verdict.serverId
+    const client = verdict.client
     const slash = endpoint.indexOf('/')
     const namespace = slash === -1 ? endpoint : endpoint.slice(0, slash)
     const method = slash === -1 ? '' : endpoint.slice(slash + 1)
@@ -3475,8 +5004,22 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
       // through the outage and reopens the leg when the relay serves again
       // (CP4); every other endpoint's first read fails out with the original
       // code (CP5 scope, the pre-CP4 behavior).
-      upstream = relay.openStream(namespace, method, clone, signal)
+      upstream = forwardsUplink
+        ? client.openStream(
+            namespace,
+            method,
+            clone,
+            signal,
+            {
+              uplink: uplink as AsyncIterable<unknown>,
+              ...(normalizedWindow !== undefined ? { uplinkWindow: normalizedWindow } : {}),
+            },
+          )
+        : client.openStream(namespace, method, clone, signal)
     } catch (error) {
+      // TA-2: a synchronous openStream failure (an unpaired relay) strands
+      // the forwarded inbox — the pump never started, so half-close it here.
+      if (forwardsUplink) releaseUplink(uplink)
       const code = error instanceof RelayError ? error.code : 'internal'
       throwRecorded(endpoint, code, messageOf(error))
     }
@@ -3489,9 +5032,28 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
     // the endpoints OUTSIDE the list end with the original code at once,
     // their consumers rendering a clean end as a terminal (CP5,
     // SESSION_STREAM_HOLD_ENDPOINTS).
-    return rewriteUpstream(endpoint, upstream, serverId, virtuals, signal, () =>
-      relay.openStream(namespace, method, clone, signal),
+    const held = rewriteUpstream(endpoint, client, upstream, serverId, virtuals, signal, () =>
+      client.openStream(namespace, method, clone, signal),
     )
+    // P55-2: a remote session/follow is recorded the instant the wrap is
+    // reached (before any frame, before any browser report) — the first
+    // <img> of the page cannot race a 1s poll. The follow stays in
+    // `activeRemoteFollows` for the generator's whole life and leaves in its
+    // finally, so the map holds exactly the LIVE follows.
+    if (endpoint === 'session/follow') {
+      const claimed = virtuals[0]
+      lastFollowedSession = { kind: 'remote', serverId: claimed.serverId, sessionId: claimed.id }
+      const token = Symbol()
+      activeRemoteFollows.set(token, { serverId: claimed.serverId, sessionId: claimed.id })
+      return (async function* () {
+        try {
+          yield* held
+        } finally {
+          activeRemoteFollows.delete(token)
+        }
+      })()
+    }
+    return held
   }
 
 
@@ -3505,11 +5067,22 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
     uninstall() {
       if (!installed) return
       installed = false
+      // P55-2: the attribution state dies with the wrap — the fetch-route
+      // half reads the wiring's live `interceptHandle` slot, which the
+      // uninstall clears, so this is hygiene; a stale map must never
+      // outlive the interception that fed it.
+      remoteSessionCwds.clear()
+      activeRemoteFollows.clear()
+      lastFollowedSession = undefined
       for (const listener of [...uninstallListeners]) listener()
       // The catalog watcher dies with the wrap (T52-fix2): a late online
-      // transition after this point belongs to another generation.
+      // transition after this point belongs to another generation. MS-5: in
+      // pool mode that includes every per-entry client subscription the
+      // rescan created — the rescan's own unsubscribe is not enough.
       offCatalogWatch?.()
       offCatalogWatch = undefined
+      for (const unsubscribe of catalogWatched.values()) unsubscribe()
+      catalogWatched.clear()
       for (const name of ['openWireStream', 'dispatchRpc']) {
         // Only replace/delete while the property still holds OUR wrapper.
         // A later plugin may have wrapped OVER us: its wrapper captured this
@@ -3544,6 +5117,13 @@ export function installIntercept(options: InstallInterceptOptions): InterceptHan
       const virtualIds = ids.filter((id) => typeof id === 'string' && id !== '' && isVirtual(id))
       if (virtualIds.length > 0) summarySync.noteForwardedSessionIds(virtualIds)
     },
+    notePoolEvent() {
+      // MS-3: broadcast to every pool watcher — the live merged streams'
+      // re-scans and the pool-mode catalog watcher (already registered as
+      // one of the listeners in pool mode). No-op in single-server mode.
+      for (const listener of [...poolListeners]) listener()
+    },
+    resolveRemoteFileScope,
   }
 }