dsh-zen-remote 2.3.11 → 2.4.1

package/src/merge-streams.ts

@@ -142,7 +142,7 @@
  * `zr~<serverId>~provider/model` fallback string (the pre-fix2 display).
  */
 
-import { fromVirtual, isVirtual, toVirtual, VIRTUAL_GROUP_NAME_MARK } from './virtual-id.js'
+import { encodeServerIdZeroWidth, fromVirtual, isVirtual, toVirtual } from './virtual-id.js'
 
 /** The (serverId, serverName) pair a merger virtualizes with. A re-handshake
  * with a different server retargets the SAME merger ({@link retarget}) so the
@@ -162,12 +162,26 @@ export interface MergerIdentity {
  * English forms live in src/client/locales.ts, `remoteGroup*` keys).
  */
 export type MergerAnnotation = 'none' | 'offline' | 'revoked' | 'unpaired' | 'mismatch'
+export type MergerLang = 'zh' | 'en'
 
-const ANNOTATION_SUFFIX: Record<Exclude<MergerAnnotation, 'none'>, string> = {
-  offline: '（离线）',
-  revoked: '（令牌已吊销）',
-  unpaired: '（已解除配对）',
-  mismatch: '（版本有差异）',
+const ANNOTATION_SUFFIX_BY_LANG: Record<MergerLang, Record<Exclude<MergerAnnotation, 'none'>, string>> = {
+  zh: {
+    offline: '（离线）',
+    revoked: '（令牌已吊销）',
+    unpaired: '（已解除配对）',
+    mismatch: '（版本有差异）',
+  },
+  en: {
+    offline: ' (offline)',
+    revoked: ' (token revoked)',
+    unpaired: ' (unpaired)',
+    mismatch: ' (version mismatch)',
+  },
+}
+
+function resolveMergerLang(lang: MergerLang | (() => MergerLang) | undefined): MergerLang {
+  const value = typeof lang === 'function' ? lang() : lang
+  return value === 'en' ? 'en' : 'zh'
 }
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -199,12 +213,13 @@ function virtualizeWorkspace(
   record: Record<string, unknown>,
   identity: MergerIdentity,
   annotation: MergerAnnotation,
+  lang: MergerLang = 'zh',
 ): Record<string, unknown> {
   const virtualize = (id: string): string => toVirtual(identity.serverId, id)
   const out: Record<string, unknown> = { ...record }
   if (typeof record.workspaceId === 'string') out.workspaceId = virtualize(record.workspaceId)
   if (typeof record.title === 'string') {
-    const suffix = annotation === 'none' ? '' : ANNOTATION_SUFFIX[annotation]
+    const suffix = annotation === 'none' ? '' : ANNOTATION_SUFFIX_BY_LANG[lang][annotation]
     out.title = `${identity.serverName} · ${record.title}${suffix}`
   }
   if (Array.isArray(record.sessionIds)) {
@@ -220,6 +235,9 @@ export interface WorkspaceMergerOptions extends MergerIdentity {
   /** T65: the clock the tombstone hide-grace runs on. Default Date.now;
    * tests advance an injectable fake to cross the grace. */
   now?: () => number
+  /** Language for status annotation suffixes on group titles (`'zh'` default,
+   * `'en'` English). Accepts a getter for live resolution. */
+  lang?: MergerLang | (() => MergerLang) | undefined
   /** PB-25b: the known-real-session inventory report — every time the
    * session registry changes, the FULL current set of real ids this merger
    * knows (the sessionHome keys: live ids and tombstones alike, each one the
@@ -234,6 +252,22 @@ export interface WorkspaceMergerOptions extends MergerIdentity {
   onKnownSessions?: (ids: ReadonlySet<string>) => void
 }
 
+/** The lists a workspace merger contributes to the MS-3 multi-server
+ * composition: the locally observed truth (identical across every slot fed
+ * the same local stream) and this server's virtualized remote contribution
+ * (shown workspaces in remote order, archived = remote archived + the T58
+ * hidden closed sessions, pinned). Snapshots — the caller may mutate them
+ * freely; nothing here hands out a live reference. */
+export interface WorkspaceMergerParts {
+  local: { orderIds: string[]; archivedIds: string[]; pinnedIds: string[] }
+  remote: {
+    orderIds: string[]
+    archivedIds: string[]
+    pinnedIds: string[]
+    workspaces: Record<string, unknown>[]
+  }
+}
+
 export interface WorkspaceMerger {
   readonly serverId: string
   readonly serverName: string
@@ -287,6 +321,13 @@ export interface WorkspaceMerger {
    * for a serverId change the remote state must be gone first (onRemoteGone
    * first); for a rename it may stay. */
   retarget(identity: MergerIdentity): void
+  /** MS-3: the composition inputs the multi-server orchestrator builds the
+   * canonical merged frames from — the locally observed lists and this
+   * server's virtualized remote contribution, as snapshots. Reading the
+   * workspaces runs the same {@link forwardVisible} visibility gate the
+   * frame paths use (T56/T58), so the parts can never expose a group the
+   * frames would withhold. */
+  parts(): WorkspaceMergerParts
 }
 
 /**
@@ -518,7 +559,7 @@ export function createWorkspaceMerger(options: WorkspaceMergerOptions): Workspac
    * session stays in its group so the host's「显示已归档」filter can show it
    * in place — hiding is purely the archived set. */
   function forwardWorkspace(record: Record<string, unknown>): Record<string, unknown> {
-    const out = virtualizeWorkspace(record, identity, annotation)
+    const out = virtualizeWorkspace(record, identity, annotation, resolveMergerLang(options.lang))
     const workspaceId = typeof record.workspaceId === 'string' ? record.workspaceId : undefined
     const live = stringList(record.sessionIds)
     if (workspaceId === undefined || !Array.isArray(out.sessionIds)) return out
@@ -627,6 +668,22 @@ export function createWorkspaceMerger(options: WorkspaceMergerOptions): Workspac
       identity = { serverId: next.serverId, serverName: next.serverName }
     },
 
+    parts(): WorkspaceMergerParts {
+      return {
+        local: {
+          orderIds: [...localOrder],
+          archivedIds: [...localArchived],
+          pinnedIds: [...localPinned],
+        },
+        remote: {
+          orderIds: remoteIds(),
+          archivedIds: [...remoteArchivedVirtual(), ...[...hiddenSessions].map(virtualize)],
+          pinnedIds: remotePinnedVirtual(),
+          workspaces: virtualWorkspaces(),
+        },
+      }
+    },
+
     onLocal(frame: unknown): unknown[] {
       if (!isPlainObject(frame)) return [frame]
       observeLocal(frame)
@@ -1243,7 +1300,9 @@ export function mergeSessionList(localResult: unknown, remoteResult: unknown, se
  *   order, RT dsh-client-ui-model-selection lib/client.js:510 — appended
  *   groups render last); each group id becomes the virtual group id
  *   `zr~<serverId>~<original>` and its name is prefixed
- *   `${VIRTUAL_GROUP_NAME_MARK}${serverName} · ${name}` — the same workspace
+ *   `${encodeServerIdZeroWidth(serverId)}${serverName} · ${name}` (MS-4: the
+ *   WORD JOINER mark plus the serverId as 32 zero-width bits, so the browser
+ *   can hide OTHER paired servers' groups too) — the same workspace
  *   title discipline the merger uses, PLUS the invisible WORD JOINER (T74):
  *   the model menu's groups stopped carrying their id in the markup (0.2.0's
  *   MenuGroup renders `aria-labelledby={useId()}` only), so the browser
@@ -1289,7 +1348,7 @@ export function mergeModelCatalogs(localValue: unknown, remoteValue: unknown, id
       ...group,
       id,
       ...(typeof group.name === 'string'
-        ? { name: `${VIRTUAL_GROUP_NAME_MARK}${identity.serverName} · ${group.name}` }
+        ? { name: `${encodeServerIdZeroWidth(identity.serverId)}${identity.serverName} · ${group.name}` }
         : {}),
     })
   }
@@ -1401,3 +1460,89 @@ export function sessionSummaryAddedFrames(remoteResult: unknown, serverId: strin
   }
   return frames
 }
+
+// ---- MS-3: multi-server composition -----------------------------------------
+
+/** The cumulative LOCAL lists one workspace merger's `local` side holds. */
+export interface LocalWorkspaceLists {
+  orderIds: string[]
+  archivedIds: string[]
+  pinnedIds: string[]
+}
+
+/**
+ * MS-3: fold one LOCAL `workspace/follow` frame into the orchestrator's
+ * cumulative local lists — the baseline replaces all three, `order` /
+ * `archived` / `pinned` each replace their own list, and every other frame
+ * (upsert / remove / junk) observes nothing. The parsing is the merger's own
+ * `observeLocal` reading, extracted so the multi-server orchestrator keeps
+ * the same truth WITHOUT a second shape definition drifting away from it.
+ */
+export function localWorkspaceLists(frame: unknown, current: LocalWorkspaceLists): LocalWorkspaceLists {
+  if (!isPlainObject(frame)) return current
+  if (frame.type === 'baseline') {
+    const value = isPlainObject(frame.value) ? frame.value : {}
+    return {
+      orderIds: idList(value.items),
+      archivedIds: stringList(value.archivedSessionIds),
+      pinnedIds: stringList(value.pinnedSessionIds),
+    }
+  }
+  if (frame.type === 'order') return { ...current, orderIds: stringList(frame.workspaceIds) }
+  if (frame.type === 'archived') return { ...current, archivedIds: stringList(frame.archivedSessionIds) }
+  if (frame.type === 'pinned') return { ...current, pinnedIds: stringList(frame.pinnedSessionIds) }
+  return current
+}
+
+/** One slot's remote contribution for {@link composeMergedWorkspaceFrames}
+ * — the `remote` half of {@link WorkspaceMergerParts}. */
+export interface RemoteWorkspaceContribution {
+  orderIds: string[]
+  archivedIds: string[]
+  pinnedIds: string[]
+  workspaces: Record<string, unknown>[]
+}
+
+/**
+ * MS-3: the canonical merged frames over N servers — local first, then each
+ * server's contribution in the given (pairing) order. The order list is
+ * plain concatenation, the archived set is DEDUPLICATED in that order (the
+ * single-server merger dedupes the same way), and pinned concatenates (the
+ * single-server pinned frame never deduped either). With no remotes the
+ * frames collapse to the local-only form.
+ */
+export function composeMergedWorkspaceFrames(
+  local: LocalWorkspaceLists,
+  remotes: readonly RemoteWorkspaceContribution[],
+): {
+  order: { type: 'order'; workspaceIds: string[] }
+  archived: { type: 'archived'; archivedSessionIds: string[] }
+  pinned: { type: 'pinned'; pinnedSessionIds: string[] }
+  workspaces: Record<string, unknown>[]
+} {
+  const orderIds = [...local.orderIds]
+  const archived: string[] = []
+  const seenArchived = new Set<string>()
+  const addArchived = (ids: readonly string[]): void => {
+    for (const id of ids) {
+      if (seenArchived.has(id)) continue
+      seenArchived.add(id)
+      archived.push(id)
+    }
+  }
+  addArchived(local.archivedIds)
+  const pinnedIds = [...local.pinnedIds]
+  const workspaces: Record<string, unknown>[] = []
+  for (const remote of remotes) {
+    orderIds.push(...remote.orderIds)
+    addArchived(remote.archivedIds)
+    pinnedIds.push(...remote.pinnedIds)
+    workspaces.push(...remote.workspaces)
+  }
+  return {
+    order: { type: 'order', workspaceIds: orderIds },
+    archived: { type: 'archived', archivedSessionIds: archived },
+    pinned: { type: 'pinned', pinnedSessionIds: pinnedIds },
+    workspaces,
+  }
+}

package/src/plugin-route-intercept.ts

@@ -340,15 +340,19 @@ export interface InstallPluginRouteInterceptOptions {
   webServer: object
   /** The local declaration registry (the `zenRemote` service's table). */
   registry: BridgeRegistry
-  /** The client relay client; `pluginRequest` is the forwarding door. */
-  relay: RelayClient
-  /** The CURRENT handshake's server id, read live per call; a virtual id
-   * minted for another server (or before any handshake) refuses
-   * `server-changed`. */
-  getServerId: () => string | undefined
-  /** The PB-2 bridge verdicts, computed live per call; a plugin that is
-   * not bridged right now refuses with the status's own reason. */
-  getStatus: () => BridgeStatus[]
+  /** SINGLE-SERVER mode: the client relay client; `pluginRequest` is the
+   * forwarding door. Required together with {@link getServerId} and
+   * {@link getStatus} unless the MS-4 per-server faces below are given
+   * (MS-5's pool wiring). */
+  relay?: RelayClient
+  /** SINGLE-SERVER mode: the CURRENT handshake's server id, read live per
+   * call; a virtual id minted for another server (or before any handshake)
+   * refuses `server-changed`. */
+  getServerId?: () => string | undefined
+  /** SINGLE-SERVER mode: the PB-2 bridge verdicts, computed live per call; a
+   * plugin that is not bridged right now refuses with the status's own
+   * reason. */
+  getStatus?: () => BridgeStatus[]
   /** The validated adapters (PB-11), as the wiring registered them.
    * Absent/empty — the pluggable default — means no adapter routes exist
    * and this interception behaves exactly as before. */
@@ -374,6 +378,18 @@ export interface InstallPluginRouteInterceptOptions {
    * consumption: nothing here mutates merge state. Absent → the scan is
    * exactly the request-local PB-22 behavior. */
   getKnownRealIds?: () => ReadonlySet<string>
+  /** MS-4: the per-server faces of the connection pool. A request whose
+   * located ids are `zr~<serverId>~…` is validated, forwarded and
+   * response-rewritten against THAT server alone: its relay client
+   * (`undefined` — a server the pool does not hold — refuses
+   * `server-changed`), its bridge verdicts and its known-real-id inventory.
+   * Each is optional and falls back on its own to the single-server face
+   * above: no `getRelayForServer` → `relay` exactly when the id belongs to
+   * `getServerId()`; no `getStatusForServer` → `getStatus()`; no
+   * `getKnownRealIdsForServer` → `getKnownRealIds()`. All read live. */
+  getRelayForServer?: (serverId: string) => RelayClient | undefined
+  getStatusForServer?: (serverId: string) => BridgeStatus[]
+  getKnownRealIdsForServer?: (serverId: string) => ReadonlySet<string>
   /** PB-26a: called with the virtual session ids a response rewrite
    * PRODUCED — a `rewriteIds.fields` route's wrapped positions, or the ids
    * an adapter's `client.response` hook passed through `virtualize` (e.g.
@@ -485,11 +501,55 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
       },
     }
   }
-  const { webServer, registry, relay, getServerId, getStatus, log } = options
+  const { webServer, registry, log } = options
   const adapters = options.adapters ?? []
   const getCurrentSession = options.getCurrentSession
   const getKnownRealIds = options.getKnownRealIds
   const onMintedVirtualIds = options.onMintedVirtualIds
+  const { relay, getServerId, getStatus } = options
+  const { getRelayForServer, getStatusForServer, getKnownRealIdsForServer } = options
+  // Exactly one mode, like installIntercept: the pool faces or the single
+  // row client — a wiring that passes neither would refuse every forwarded
+  // request as server-changed / not-bridged, so it is refused here instead.
+  if (
+    (getRelayForServer === undefined && (relay === undefined || getServerId === undefined))
+    || (getStatusForServer === undefined && getStatus === undefined)
+  ) {
+    throw new Error(
+      'installPluginRouteIntercept requires either `relay` + `getServerId` + `getStatus` (single server) or `getRelayForServer` + `getStatusForServer` (pool)',
+    )
+  }
+  // The single-server facts, proven present by the guard above.
+  const singleRelay = relay as RelayClient
+  const singleGetServerId = getServerId as () => string | undefined
+  const singleGetStatus = getStatus as () => BridgeStatus[]
+  /** MS-4: the relay client serving one server id, or `undefined` (the
+   * `server-changed` refusal). */
+  const relayOfServer = (serverId: string): RelayClient | undefined =>
+    getRelayForServer !== undefined ? getRelayForServer(serverId) : serverId === singleGetServerId() ? singleRelay : undefined
+  const statusesOfServer = (serverId: string): BridgeStatus[] =>
+    getStatusForServer !== undefined ? getStatusForServer(serverId) : singleGetStatus()
+  const knownRealIdsOfServer = (serverId: string): ReadonlySet<string> | undefined =>
+    getKnownRealIdsForServer !== undefined ? getKnownRealIdsForServer(serverId) : getKnownRealIds?.()
+  /** MS-4: the one server every located virtual id of a request belongs to,
+   * with its relay client — or the refusal reason, judged id by id in hit
+   * order (the single-server walls' order). A request naming ids of two
+   * servers is refused like a foreign one: it has no single home. */
+  const serverOfHits = (hits: readonly AdapterIdHit[]): { serverId: string; relay: RelayClient } | 'bad-query' | 'server-changed' => {
+    let located: { serverId: string; relay: RelayClient } | undefined
+    for (const idHit of hits) {
+      const parts = fromVirtual(idHit.value)
+      if (parts === undefined || parts.id === '') return 'bad-query'
+      if (located === undefined) {
+        const target = relayOfServer(parts.serverId)
+        if (target === undefined) return 'server-changed'
+        located = { serverId: parts.serverId, relay: target }
+      } else if (parts.serverId !== located.serverId) {
+        return 'server-changed'
+      }
+    }
+    return located ?? 'bad-query'
+  }
   const target = webServer as { match: (this: unknown, pathname: string) => unknown }
   const savedMatch = target.match
 
@@ -661,7 +721,8 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         answerUnbridged(res, declared.plugin, 'bad-query')
         return
       }
-      if (parts.serverId !== getServerId()) {
+      const targetRelay = relayOfServer(parts.serverId)
+      if (targetRelay === undefined) {
         answerUnbridged(res, declared.plugin, 'server-changed')
         return
       }
@@ -687,7 +748,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         log?.('plugin request for %s refused locally: body-too-large (%s declared)', declared.path, req.headers['content-length'])
         return
       }
-      const status = getStatus().find((entry) => entry.plugin === declared.plugin)
+      const status = statusesOfServer(parts.serverId).find((entry) => entry.plugin === declared.plugin)
       if (status === undefined || !status.bridged) {
         answerUnbridged(res, declared.plugin, status?.reason ?? 'not-on-server')
         return
@@ -757,7 +818,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           bodyStream = Readable.toWeb(gate) as ReadableStream<Uint8Array>
           req.pipe(gate)
         }
-        const response = await relay.pluginRequest(
+        const response = await targetRelay.pluginRequest(
           {
             plugin: declared.plugin,
             version: declared.version,
@@ -794,7 +855,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         // known inventory, read live right here (undefined when the wiring
         // passed no getter — the scan stays request-local).
         if (declared.rewriteIds) {
-          await answerRewriteIds(res, response, idMapping, declared.rewriteFields, parts.serverId, getKnownRealIds?.(), onMintedVirtualIds)
+          await answerRewriteIds(res, response, idMapping, declared.rewriteFields, parts.serverId, knownRealIdsOfServer(parts.serverId), onMintedVirtualIds)
           return
         }
         const contentType = response.headers.get('content-type')
@@ -989,7 +1050,6 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           answerUnbridged(res, plugin, 'method-not-bridged')
           return
         }
-        const serverId = getServerId()
         // PB-22: the request's own real→virtual pairs, collected while the
         // wall validates each hit — the READ-ONLY mapping a rewriteIds
         // route's answer scan consults (`zr~` carries the real id inside, so
@@ -1001,24 +1061,19 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         // ONE more source beside this mapping — the known-real-session
         // inventory, read live at the answer (never copied here) and
         // consumed read-only; nothing here writes any session table.
-        const idMapping = new Map<string, string>()
-        let locatedServerId: string | undefined
-        for (const idHit of verdict.hits) {
-          const parts = fromVirtual(idHit.value)
-          if (parts === undefined || parts.id === '') {
-            answerUnbridged(res, plugin, 'bad-query')
-            return
-          }
-          if (parts.serverId !== serverId) {
-            answerUnbridged(res, plugin, 'server-changed')
-            return
-          }
-          idMapping.set(parts.id, idHit.value)
-          locatedServerId = parts.serverId
+        // MS-4: every located id must name ONE server the wiring serves;
+        // that server's relay, verdicts and inventory carry the rest.
+        const home = serverOfHits(verdict.hits)
+        if (home === 'bad-query' || home === 'server-changed') {
+          answerUnbridged(res, plugin, home)
+          return
         }
+        const locatedServerId = home.serverId
+        const idMapping = new Map<string, string>()
+        for (const idHit of verdict.hits) idMapping.set(fromVirtual(idHit.value)!.id, idHit.value)
         // The bridge verdicts judged from the SAME live table the query
         // half reads.
-        const status = getStatus().find((entry) => entry.plugin === plugin)
+        const status = statusesOfServer(locatedServerId).find((entry) => entry.plugin === plugin)
         if (status === undefined || !status.bridged) {
           answerUnbridged(res, plugin, status?.reason ?? 'not-on-server')
           return
@@ -1078,7 +1133,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           req.pipe(gate)
           if (Number.isFinite(declaredLength) && declaredLength > 0) contentLength = declaredLength
         }
-        const response = await relay.pluginRequest(
+        const response = await home.relay.pluginRequest(
           {
             plugin,
             version: declared.version,
@@ -1104,7 +1159,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           return
         }
         if (declared.rewriteIds) {
-          await answerRewriteIds(res, response, idMapping, declared.rewriteFields, locatedServerId!, getKnownRealIds?.(), onMintedVirtualIds)
+          await answerRewriteIds(res, response, idMapping, declared.rewriteFields, locatedServerId, knownRealIdsOfServer(locatedServerId), onMintedVirtualIds)
           return
         }
         const contentType = response.headers.get('content-type')
@@ -1300,23 +1355,18 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           answerUnbridged(res, plugin, 'method-not-bridged')
           return
         }
-        const serverId = getServerId()
-        for (const idHit of verdict.hits) {
-          const parts = fromVirtual(idHit.value)
-          if (parts === undefined || parts.id === '') {
-            answerUnbridged(res, plugin, 'bad-query')
-            return
-          }
-          if (parts.serverId !== serverId) {
-            answerUnbridged(res, plugin, 'server-changed')
-            return
-          }
+        // MS-4: one home server for every located id.
+        const home = serverOfHits(verdict.hits)
+        if (home === 'bad-query' || home === 'server-changed') {
+          answerUnbridged(res, plugin, home)
+          return
         }
+        const serverId = home.serverId
         // The bridge verdicts (version skew, consent, offline…) judged from
         // the SAME live table the cooperative surrogate reads — the
         // adapter's registry entry makes the plugin indistinguishable from
         // a cooperative one here.
-        const status = getStatus().find((entry) => entry.plugin === plugin)
+        const status = statusesOfServer(serverId).find((entry) => entry.plugin === plugin)
         if (status === undefined || !status.bridged) {
           answerUnbridged(res, plugin, status?.reason ?? 'not-on-server')
           return
@@ -1375,7 +1425,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           bodyStream = Readable.toWeb(gate) as ReadableStream<Uint8Array>
           req.pipe(gate)
         }
-        const response = await relay.pluginRequest(
+        const response = await home.relay.pluginRequest(
           {
             plugin,
             version: adapter.declaration.version,
@@ -1480,7 +1530,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
             pathname,
             body: JSON.parse(text),
             virtualize: (id: string) => {
-              const virtualId = toVirtual(serverId ?? '', id)
+              const virtualId = toVirtual(serverId, id)
               if (isVirtual(virtualId)) minted.add(virtualId)
               return virtualId
             },
@@ -1744,6 +1794,9 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
 
       // ---- the remote pipe: the PB-10 tunnel, frame by frame -------------
       let tunnelHandle: { tunnel: string; frames: AsyncIterable<Uint8Array> } | undefined
+      // MS-4: the server the tunnel was opened on — set together with
+      // tunnelHandle, the relay every later send and the close travel.
+      let tunnelServer: { serverId: string; relay: RelayClient } | undefined
       // The connection-wide real→virtual mapping the rewriteIds deep scan
       // consults: EVERY validated remote frame's ids merge in (a watch list
       // that grows mid-connection makes the later answers rewritable too —
@@ -1764,7 +1817,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
        * never a silent broken flag: that would leak `tunnelsCurrent` and
        * leave the browser hanging on a dead tunnel. */
       const sendTextUpstream = async (frame: Rfc6455Frame, parsedJson: unknown, hits: AdapterIdHit[]): Promise<void> => {
-        if (upstreamBroken || tunnelHandle === undefined) return
+        if (upstreamBroken || tunnelHandle === undefined || tunnelServer === undefined) return
         const rewrite = hits.length > 0
           ? rewriteAdapterRequest(declared.view, declared.path, new URLSearchParams(), parsedJson, hits, (virtualId) => fromVirtual(virtualId)!.id)
           : undefined
@@ -1772,7 +1825,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         const seq = upstreamSeq
         upstreamSeq += 1
         try {
-          await relay.pluginTunnelSend(tunnelHandle.tunnel, seq, encodeRfc6455Frame(0x1, payload, true, frame.fin))
+          await tunnelServer.relay.pluginTunnelSend(tunnelHandle.tunnel, seq, encodeRfc6455Frame(0x1, payload, true, frame.fin))
         } catch {
           killExchange()
         }
@@ -1819,7 +1872,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
                     })), 'utf8')
                     hooked = true
                   } else if (declared.rewriteIds) {
-                    const scanned = deepRewriteIds(parsedJson, idMapping, getKnownRealIds?.(), serverId)
+                    const scanned = deepRewriteIds(parsedJson, idMapping, knownRealIdsOfServer(serverId), serverId)
                     if (declared.rewriteFields !== undefined) rewriteIdsAtFields(scanned, declared.rewriteFields, serverId)
                     outPayload = Buffer.from(JSON.stringify(scanned), 'utf8')
                     hooked = true
@@ -1917,24 +1970,18 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           }
           return
         }
-        const serverId = getServerId()
-        if (serverId === undefined) {
+        // MS-4: the frame's ids name one served server, and once the tunnel
+        // is open every later frame must name the tunnel's own server.
+        const home = serverOfHits(verdict.hits)
+        if (home === 'bad-query' || home === 'server-changed' || (tunnelServer !== undefined && home.serverId !== tunnelServer.serverId)) {
           refuseAndDie('server-changed')
           return
         }
-        const mapping = new Map<string, string>()
-        for (const idHit of verdict.hits) {
-          const parts = fromVirtual(idHit.value)
-          if (parts === undefined || parts.id === '' || parts.serverId !== serverId) {
-            refuseAndDie('server-changed')
-            return
-          }
-          mapping.set(parts.id, idHit.value)
-        }
+        const serverId = home.serverId
         // This frame's ids join the connection-wide mapping (see idMapping).
-        for (const [key, value] of mapping) idMapping.set(key, value)
+        for (const idHit of verdict.hits) idMapping.set(fromVirtual(idHit.value)!.id, idHit.value)
         if (tunnelHandle === undefined) {
-          const status = getStatus().find((entry) => entry.plugin === plugin)
+          const status = statusesOfServer(serverId).find((entry) => entry.plugin === plugin)
           if (status === undefined || !status.bridged) {
             refuseAndDie(status?.reason ?? 'not-on-server')
             return
@@ -1944,7 +1991,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           let opened: { tunnel: string; frames: AsyncIterable<Uint8Array> }
           try {
             log?.('opening tunnel for %s', declared.path)
-            opened = await relay.pluginTunnelOpen(
+            opened = await home.relay.pluginTunnelOpen(
               {
                 plugin,
                 version: declared.version,
@@ -1962,6 +2009,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           }
           tunnelsCurrent += 1
           tunnelsOpened += 1
+          tunnelServer = home
           tunnelHandle = opened
           log?.('tunnel open for %s: %s', declared.path, opened.tunnel)
           teardownTunnel = (): void => {
@@ -1969,7 +2017,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
             upstreamBroken = true
             tunnelsCurrent -= 1
             tunnelsClosed += 1
-            void relay.pluginTunnelClose(opened.tunnel).catch(() => {})
+            void home.relay.pluginTunnelClose(opened.tunnel).catch(() => {})
           }
           socket.on('close', teardownTunnel)
           socket.on('error', teardownTunnel)
@@ -1988,11 +2036,11 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
             localSocket.push(frame.raw)
             return
           }
-          if (tunnelHandle !== undefined && !upstreamBroken) {
+          if (tunnelHandle !== undefined && tunnelServer !== undefined && !upstreamBroken) {
             const seq = upstreamSeq
             upstreamSeq += 1
             try {
-              await relay.pluginTunnelSend(tunnelHandle.tunnel, seq, frame.raw)
+              await tunnelServer.relay.pluginTunnelSend(tunnelHandle.tunnel, seq, frame.raw)
             } catch {
               // The send died: tear the exchange down COMPLETELY — the
               // counter, the close, the browser socket (a bare broken flag
@@ -2100,7 +2148,8 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           answerUnbridgedSocket(socket, declared.plugin, 'bad-query')
           return
         }
-        if (parts.serverId !== getServerId()) {
+        const tunnelRelay = relayOfServer(parts.serverId)
+        if (tunnelRelay === undefined) {
           answerUnbridgedSocket(socket, declared.plugin, 'server-changed')
           return
         }
@@ -2108,7 +2157,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         // the tunnel opens only for a plugin bridged RIGHT NOW — an absent
         // or unbridged status refuses with its own reason, and the local
         // plugin handler is never reached.
-        const bridgeStatus = getStatus().find((entry) => entry.plugin === declared.plugin)
+        const bridgeStatus = statusesOfServer(parts.serverId).find((entry) => entry.plugin === declared.plugin)
         if (bridgeStatus === undefined || !bridgeStatus.bridged) {
           answerUnbridgedSocket(socket, declared.plugin, bridgeStatus?.reason ?? 'not-on-server')
           return
@@ -2129,7 +2178,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         let tunnel: { tunnel: string; frames: AsyncIterable<Uint8Array> }
         try {
           log?.('opening tunnel for %s', declared.path)
-          tunnel = await relay.pluginTunnelOpen(
+          tunnel = await tunnelRelay.pluginTunnelOpen(
             {
               plugin: declared.plugin,
               version: declared.version,
@@ -2207,7 +2256,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
             pending = pending.then(async () => {
               if (upstreamBroken) return
               try {
-                await relay.pluginTunnelSend(tunnel.tunnel, seq, bytes, controller.signal)
+                await tunnelRelay.pluginTunnelSend(tunnel.tunnel, seq, bytes, controller.signal)
               } catch {
                 upstreamBroken = true
               }
@@ -2218,7 +2267,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           upstreamBroken = true
           tunnelsCurrent -= 1
           tunnelsClosed += 1
-          void relay.pluginTunnelClose(tunnel.tunnel).catch(() => {})
+          void tunnelRelay.pluginTunnelClose(tunnel.tunnel).catch(() => {})
         }
         socket.on('close', teardownTunnel)
         socket.on('error', teardownTunnel)