dsh-zen-remote 2.3.10 → 2.4.0

package/src/cli/main.ts

@@ -0,0 +1,285 @@
+/**
+ * CLI-5: the process entry point behind `bin/zen-remote.mjs`. `runCli` turns
+ * a parsed argv into exactly one verdict: static answers (help, version,
+ * the SPEC's `--role peer` refusal, unknown commands) render here; every
+ * plugin-driving command first comes alive through `ensureDshRunning` and
+ * then dispatches into the CLI-3/CLI-4 command functions over the discovered
+ * IPC socket; `setup` owns its preflight (install + launch) and runs the
+ * three-step wizard.
+ *
+ * Two things belong ONLY here: the interactivity verdict for the whole run
+ * (TTY && !`--yes`, with the default readline prompter created lazily and —
+ * importantly — closed in the end, or an unanswered stdin handle would keep
+ * the process alive after the answer printed), and the structured error
+ * boundary that turns a MissingRequiredOptionError into one precise
+ * bilingual line instead of a stack trace. All dependencies are injectable
+ * so the tests drive the real entry function with fakes (SPEC's test seam
+ * three).
+ */
+
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseCliArgs } from './args.js'
+import type { ParsedCliArgs } from './args.js'
+import { createReadlinePrompter, ensureDshRunning, isInteractiveSession, MissingRequiredOptionError } from './bootstrap.js'
+import type { CliPrompter, ExecProbe } from './bootstrap.js'
+import { discoverCliSockets } from './ipc-client.js'
+import { CLI_PROTOCOL_VERSION } from './ipc-server.js'
+import { createTranslator, resolveCliLang } from './i18n.js'
+import type { CliTranslator } from './i18n.js'
+import { runStatusCommand } from './commands-status.js'
+import { runClientListCommand, runClientPairCommand, runClientUnpairCommand } from './commands-client.js'
+import {
+  runHostDeviceListCommand,
+  runHostDevicePairCommand,
+  runHostDeviceRevokeCommand,
+  runHostIngressSnippetCommand,
+  runHostIngressStartCommand,
+  runHostIngressStopCommand,
+  runHostIngressVerifyCommand,
+} from './commands-host.js'
+import { runSetupCommand } from './command-setup.js'
+import type { SetupCommandContext } from './command-setup.js'
+
+export interface CliRuntimeDeps {
+  /** Environment for the language resolution and the `DSH_HOME` fallback. */
+  env?: NodeJS.ProcessEnv
+  /** The DSH home the sockets / profiles live under. Default
+   * `<env.DSH_HOME ?? ~/.dsh>` — the same resolution config.ts uses. */
+  dshHome?: string
+  /** Whether this run can prompt. Default `process.stdin.isTTY === true`. */
+  isTty?: boolean
+  stdout?: { write(text: string): void }
+  /** The ask-everything funnel; the default readline prompter is built
+   * lazily (and closed at the end) when a run may actually prompt. */
+  prompter?: CliPrompter
+  /** `--version`'s answer; default the package.json version next to lib/. */
+  packageVersion?: string
+  /** Bind-shape override (tests pin every platform branch). */
+  platform?: NodeJS.Platform
+  /** uid for the launchd `gui/<uid>/…` target. */
+  uid?: number
+  macosAppPath?: string
+  systemUnitDir?: string
+  /** Test seams, forwarded into the preflight / bootstrap. */
+  discover?: typeof discoverCliSockets
+  spawnCommand?: (command: string, args: readonly string[]) => Promise<number>
+  execProbe?: ExecProbe
+  now?: () => Date
+  cwd?: string
+  pollIntervalMs?: number
+  abortSignal?: AbortSignal
+}
+
+function readPackageVersion(): string {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf8'))
+    if (parsed !== null && typeof parsed === 'object') {
+      const version = (parsed as { version?: unknown }).version
+      if (typeof version === 'string') return version
+    }
+  } catch { /* packaged oddities fall back to a visible placeholder */ }
+  return 'unknown'
+}
+
+/** The complete bilingual command tree — the `help.command.*` /
+ * `help.option.*` dictionary keys ARE the tree's source of truth. */
+function printHelp(t: CliTranslator, out: { write(text: string): void }): void {
+  const lines = [
+    t('help.title'),
+    '',
+    t('help.usage'),
+    '',
+    t('help.description'),
+    '',
+    t('help.commands'),
+    `  ${t('help.command.setup')}`,
+    `  ${t('help.command.status')}`,
+    `  ${t('help.command.hostDevice')}`,
+    `  ${t('help.command.hostIngress')}`,
+    `  ${t('help.command.clientPair')}`,
+    `  ${t('help.command.clientUnpair')}`,
+    `  ${t('help.command.clientList')}`,
+    '',
+    t('help.options'),
+    ...([
+      'lang', 'json', 'socket', 'wait', 'yes', 'noWait', 'debug', 'role', 'profile',
+      'ingress', 'domain', 'cfToken', 'email', 'httpsPort', 'publicUrl', 'tunnelId',
+      'proxy', 'deviceRole', 'hostUrl', 'code', 'name', 'all',
+    ] as const).map((option) => `  ${t(`help.option.${option}`)}`),
+    '',
+    t('help.footer'),
+  ]
+  out.write(`${lines.join('\n')}\n`)
+}
+
+/** The static verdicts that need no plugin and no IPC, in priority order. */
+function staticVerdict(parsed: ParsedCliArgs, t: CliTranslator, out: { write(text: string): void }, packageVersion: string): number | undefined {
+  if (parsed.command === 'help') {
+    printHelp(t, out)
+    return 0
+  }
+  if (parsed.command === 'version') {
+    out.write(`${packageVersion}\n`)
+    return 0
+  }
+  if (parsed.options.roleIssue === 'peer-not-enabled') {
+    out.write(`${t('err.role.peerNotEnabled')}\n`)
+    return 1
+  }
+  if (parsed.options.roleIssue === 'invalid') {
+    out.write(`${t('err.role.invalid', { value: parsed.options.role ?? '' })}\n`)
+    return 1
+  }
+  if (parsed.command === 'unknown') {
+    out.write(`${t('err.unknownCommand', { command: parsed.unknownCommand ?? '' })}\n`)
+    return 1
+  }
+  return undefined
+}
+
+/**
+ * Run one CLI invocation (argv WITHOUT the node binary and script path) and
+ * answer its exit code. The bin entry assigns it to `process.exitCode`.
+ */
+export async function runCli(argv: readonly string[], deps?: CliRuntimeDeps): Promise<number> {
+  const d = deps ?? {}
+  const parsed = parseCliArgs(argv)
+  const env = d.env ?? process.env
+  const t = createTranslator(resolveCliLang(parsed.options.lang, env))
+  const out = d.stdout ?? process.stdout
+  const dshHome = d.dshHome ?? env.DSH_HOME ?? join(homedir(), '.dsh')
+  const interactive = isInteractiveSession(parsed, d.isTty ?? process.stdin.isTTY === true)
+
+  // The default readline prompter is created lazily and owned by this run —
+  // an unclosed one would hold stdin open after the answer is printed.
+  let ownedPrompter: CliPrompter | undefined
+  const prompterFor = (): CliPrompter | undefined => {
+    if (!interactive) return undefined
+    if (d.prompter !== undefined) return d.prompter
+    if (ownedPrompter === undefined) ownedPrompter = createReadlinePrompter(undefined, undefined, t)
+    return ownedPrompter
+  }
+
+  // The real Ctrl-C seam (context.ts's contract): without an injected signal,
+  // the process's SIGINT drives a run-owned AbortController, so the verify
+  // wait can skip gracefully. A SECOND Ctrl-C force-quits — the listener must
+  // never swallow Ctrl-C for phases that cannot react to the signal. The
+  // listener is removed in the end; nothing leaks across runs (or into the
+  // tests' process).
+  const controller = new AbortController()
+  const onSigint = (): void => {
+    if (controller.signal.aborted) {
+      process.exit(130)
+      return
+    }
+    controller.abort()
+  }
+  if (d.abortSignal === undefined) process.on('SIGINT', onSigint)
+  const abortSignal = d.abortSignal ?? controller.signal
+
+  try {
+    const verdict = staticVerdict(parsed, t, out, d.packageVersion ?? readPackageVersion())
+    if (verdict !== undefined) return verdict
+
+    if (parsed.command === 'setup') {
+      const setupCtx: SetupCommandContext = {
+        args: parsed,
+        dshHome,
+        interactive,
+        t,
+        stdout: out,
+        ...(interactive ? { prompter: prompterFor() } : {}),
+        ...(d.pollIntervalMs === undefined ? {} : { pollIntervalMs: d.pollIntervalMs }),
+        abortSignal,
+        ...(d.now === undefined ? {} : { now: d.now }),
+        ...(d.cwd === undefined ? {} : { cwd: d.cwd }),
+        ...(d.discover === undefined ? {} : { discover: d.discover }),
+        ...(d.spawnCommand === undefined ? {} : { spawnCommand: d.spawnCommand }),
+        ...(d.execProbe === undefined ? {} : { execProbe: d.execProbe }),
+        ...(d.platform === undefined ? {} : { platform: d.platform }),
+        ...(d.uid === undefined ? {} : { uid: d.uid }),
+        ...(d.macosAppPath === undefined ? {} : { macosAppPath: d.macosAppPath }),
+        ...(d.systemUnitDir === undefined ? {} : { systemUnitDir: d.systemUnitDir }),
+      }
+      return await runSetupCommand(setupCtx)
+    }
+
+    // status / host.* / client.*: a live plugin is the precondition — find
+    // it (a version-mismatching socket is its own refusal) and bind.
+    const discover = d.discover ?? discoverCliSockets
+    const platform = d.platform ?? process.platform
+    const found = await discover({
+      dshHome,
+      ...(parsed.options.socket === undefined ? {} : { explicitSocket: parsed.options.socket }),
+      platform,
+    })
+    if (found.live.length === 0 && found.versionMismatch.length > 0) {
+      const mismatched = found.versionMismatch[0]
+      out.write(`${t('err.protocolVersion', {
+        found: String(mismatched?.cliProtocolVersion ?? '?'),
+        expected: CLI_PROTOCOL_VERSION,
+      })}\n`)
+      return 1
+    }
+    const up = await ensureDshRunning({
+      dshHome,
+      waitSeconds: parsed.options.wait,
+      ...(parsed.options.socket === undefined ? {} : { explicitSocket: parsed.options.socket }),
+      ...(d.platform === undefined ? {} : { platform: d.platform }),
+      ...(d.uid === undefined ? {} : { uid: d.uid }),
+      ...(d.execProbe === undefined ? {} : { execProbe: d.execProbe }),
+      discover,
+      ...(d.macosAppPath === undefined ? {} : { macosAppPath: d.macosAppPath }),
+      ...(d.systemUnitDir === undefined ? {} : { systemUnitDir: d.systemUnitDir }),
+      stdout: out,
+      t,
+    })
+    if (!up.started) return 1
+    const ipc = up.client
+    const prompter = prompterFor()
+    const ctx = {
+      args: parsed,
+      ipc,
+      t,
+      interactive,
+      ...(prompter === undefined ? {} : { prompter }),
+      stdout: out,
+      ...(d.now === undefined ? {} : { now: d.now }),
+      ...(d.cwd === undefined ? {} : { cwd: d.cwd }),
+      ...(d.pollIntervalMs === undefined ? {} : { pollIntervalMs: d.pollIntervalMs }),
+      abortSignal,
+    }
+    switch (parsed.command) {
+      case 'status': return await runStatusCommand(ctx)
+      case 'host.device.pair': return await runHostDevicePairCommand(ctx)
+      case 'host.device.list': return await runHostDeviceListCommand(ctx)
+      case 'host.device.revoke': return await runHostDeviceRevokeCommand(ctx)
+      case 'host.ingress.start': return await runHostIngressStartCommand(ctx)
+      case 'host.ingress.stop': return await runHostIngressStopCommand(ctx)
+      case 'host.ingress.verify': return await runHostIngressVerifyCommand(ctx)
+      case 'host.ingress.snippet': return await runHostIngressSnippetCommand(ctx)
+      case 'client.pair': return await runClientPairCommand(ctx)
+      case 'client.unpair': return await runClientUnpairCommand(ctx)
+      case 'client.list': return await runClientListCommand(ctx)
+      default: {
+        // staticVerdict already handled help / version / unknown / setup —
+        // the default arm is unreachable and only satisfies the exhaustiveness.
+        out.write(`${t('err.unknownCommand', { command: parsed.unknownCommand ?? '' })}\n`)
+        return 1
+      }
+    }
+  } catch (error) {
+    if (error instanceof MissingRequiredOptionError) {
+      out.write(`${t('err.missingOption', { option: error.optionName })}\n`)
+      return 1
+    }
+    out.write(`${t('err.internal', { error: error instanceof Error ? error.message : String(error) })}\n`)
+    return 1
+  } finally {
+    if (d.abortSignal === undefined) process.removeListener('SIGINT', onSigint)
+    ownedPrompter?.close()
+  }
+}

package/src/cli/qr-terminal.ts

@@ -0,0 +1,49 @@
+/**
+ * CLI-2 terminal QR rendering, zero dependencies: reuse the repo's own
+ * minimal encoder (`src/client-data/qr.ts`) and draw the module matrix with
+ * Unicode half-block characters — two module ROWS per terminal line, so the
+ * symbol stays square on screen (terminal cells are roughly twice as tall as
+ * they are wide):
+ *
+ *   dark top + dark bottom → `█`   dark top + light bottom → `▀`
+ *   light top + dark bottom → `▄`  light top + light bottom → ` `
+ *
+ * A 2-module quiet zone of light modules surrounds the symbol on every side
+ * (ISO 18004 recommendance) — without it many scanners refuse to lock on.
+ * Text too long for the encoder (over 106 UTF-8 bytes, its version-5-L
+ * capacity) returns `null`; the caller shows the plain URL instead.
+ */
+
+import { qrMatrix } from '../client-data/qr.js'
+
+const QUIET_ZONE_MODULES = 2
+
+export function renderTerminalQr(text: string): string | null {
+  const matrix = qrMatrix(text)
+  if (matrix === null) return null
+  const size = matrix.length
+  const dim = size + QUIET_ZONE_MODULES * 2
+
+  // Padded matrix: quiet zone (light) + the symbol itself.
+  const dark: boolean[][] = Array.from({ length: dim }, () => new Array<boolean>(dim).fill(false))
+  for (let row = 0; row < size; row += 1) {
+    const source = matrix[row]
+    const target = dark[row + QUIET_ZONE_MODULES]
+    if (source === undefined || target === undefined) continue
+    for (let col = 0; col < size; col += 1) target[col + QUIET_ZONE_MODULES] = source[col] ?? false
+  }
+
+  const lines: string[] = []
+  for (let row = 0; row < dim; row += 2) {
+    const top = dark[row] ?? []
+    const bottom = dark[row + 1] ?? []
+    let line = ''
+    for (let col = 0; col < dim; col += 1) {
+      const topDark = top[col] ?? false
+      const bottomDark = bottom[col] ?? false
+      line += topDark && bottomDark ? '█' : topDark ? '▀' : bottomDark ? '▄' : ' '
+    }
+    lines.push(line)
+  }
+  return lines.join('\n')
+}

package/src/client/RemoteStatusIcon.tsx

@@ -53,7 +53,10 @@ export function RemoteStatusIcon({ sessionId, status, t }: RemoteStatusIconProps
   // The explicit virtual-id gate stays: the page-wide store's snapshot can
   // still be ready from a PREVIOUS remote session when a local one opens.
   if (!isVirtual(sessionId) || !snap.ready) return null
-  const description = describeRemoteStatus(snap.view, t)
+  // MS-6: the session's virtual id picks its OWN server's entry — with
+  // several servers paired, A online and B offline light and grey their own
+  // sessions independently.
+  const description = describeRemoteStatus(snap.view, t, sessionId)
   const close = (): void => {
     // Offline recovers on its own; revoked / unpaired do not (T34-fix) —
     // each says its own word instead of "reconnecting".

package/src/client/current-session-report.ts

@@ -64,6 +64,10 @@ export interface CurrentSessionReporterOptions {
   intervalMs?: number
   /** The unconditional re-send window (T66); default 30000ms. */
   resendIntervalMs?: number
+  /** Optional UI language reader (`'zh'` | `'en'`); when present (or when
+   * `<html lang>` is set in the browser), the value rides the POST body as
+   * `lang` so the backend merger can localize sidebar group suffixes. */
+  getLang?: () => 'zh' | 'en' | undefined
 }
 
 /** One reportable value — `unavailable` never travels. */
@@ -83,9 +87,19 @@ export function startCurrentSessionReporter(options: CurrentSessionReporterOptio
       return undefined
     }
   }
-  const post = (report: ReportableReport): Promise<unknown> => {
+  const readLang = (): 'zh' | 'en' | undefined => {
+    if (options.getLang !== undefined) return options.getLang()
+    const doc = (globalThis as { document?: { documentElement?: { lang?: unknown } } }).document
+    const htmlLang = doc?.documentElement?.lang
+    if (typeof htmlLang === 'string' && htmlLang !== '') {
+      return htmlLang.toLowerCase().startsWith('zh') ? 'zh' : 'en'
+    }
+    return undefined
+  }
+  const post = (report: ReportableReport, lang: 'zh' | 'en' | undefined): Promise<unknown> => {
     const doFetch = options.fetchImpl ?? fetch
-    const body = report.kind === 'open' ? { sessionId: report.sessionId } : { sessionId: null }
+    const base = report.kind === 'open' ? { sessionId: report.sessionId } : { sessionId: null }
+    const body = lang !== undefined ? { ...base, lang } : base
     return doFetch(options.route ?? CURRENT_SESSION_ROUTE, {
       method: 'POST',
       headers: { 'content-type': 'application/json; charset=utf-8' },
@@ -100,6 +114,7 @@ export function startCurrentSessionReporter(options: CurrentSessionReporterOptio
   // T66: the timestamp of the last accepted post drives the slow unconditional
   // re-send (0 = due immediately, which is the page-load post).
   let lastReported: CurrentSessionReport | undefined
+  let lastReportedLang: 'zh' | 'en' | undefined
   let lastSentAt = 0
   const resendEveryMs = options.resendIntervalMs ?? RESEND_INTERVAL_MS
   let role: 'host' | 'client' | undefined
@@ -115,15 +130,24 @@ export function startCurrentSessionReporter(options: CurrentSessionReporterOptio
     if (role !== 'client') return
     const report = parseCurrentSessionStorage(readRaw())
     if (report.kind === 'unavailable') return
+    const lang = readLang()
     const now = Date.now()
     // T66: inside the re-send window an unchanged value says nothing; once
     // the window passes, the CURRENT value re-posts even unchanged — the
     // backend may have been reset underneath the page.
     const resendDue = now - lastSentAt >= resendEveryMs
-    if (!resendDue && lastReported !== undefined && currentSessionReportEquals(report, lastReported)) return
+    if (
+      !resendDue &&
+      lastReported !== undefined &&
+      currentSessionReportEquals(report, lastReported) &&
+      lang === lastReportedLang
+    ) {
+      return
+    }
     try {
-      await post(report)
+      await post(report, lang)
       lastReported = report
+      lastReportedLang = lang
       lastSentAt = now
     } catch {
       // Silent: the next tick sees the unchanged lastReported and retries.

package/src/client/effects/model-group-side.ts

@@ -1,5 +1,5 @@
 import type { ClientContext } from '../compat/types.ts'
-import { classifyModelGroups, type ModelGroupHeading } from '../../client-data/model-group-side.ts'
+import { classifyModelGroupsForSession, REMOTE_SERVER_ATTRIBUTE, type ModelGroupHeading, type ModelGroupSide } from '../../client-data/model-group-side.ts'
 
 /**
  * T74: stamp every model-menu group with the side of the pairing it belongs
@@ -11,6 +11,13 @@ import { classifyModelGroups, type ModelGroupHeading } from '../../client-data/m
  * virtual-id.ts) heading is decided at all, so every other menu and the
  * whole rest of the page is never touched.
  *
+ * MS-4: the open remote session's server id (`data-zr-remote-server` on
+ * <html>, written by effects/remote-session.ts) is the classifier's
+ * `activeRemoteServerId` — a remote group whose heading decodes to a
+ * DIFFERENT paired server is stamped `remote-other`. Switching between two
+ * servers' sessions changes no group DOM at all, so a second observer
+ * watches that one <html> attribute and rescans the moment it moves.
+ *
  * Synchronous in the observer callback, never behind rAF: the callback is a
  * microtask and runs before this frame paints, so a group that must be
  * hidden is hidden the first time it is drawn. A rAF would land a frame late
@@ -22,8 +29,8 @@ import { classifyModelGroups, type ModelGroupHeading } from '../../client-data/m
 const GROUP_SELECTOR = 'section[role="group"]'
 
 /** The stamp this effect writes; remote-session.css.ts hides
- * `[data-zr-group="local"]` in a remote session and
- * `[data-zr-group="remote"]` everywhere else. */
+ * `[data-zr-group="local"]` and `[data-zr-group="remote-other"]` in a
+ * remote session and both remote stamps everywhere else. */
 const STAMP = 'data-zr-group'
 
 /**
@@ -69,7 +76,7 @@ function isGroupish(node: Node): boolean {
 
 export function installModelGroupSide(ctx: ClientContext): void {
   ctx.effect(() => {
-    const applyVerdict = (section: Element, verdict: 'remote' | 'local' | undefined): void => {
+    const applyVerdict = (section: Element, verdict: ModelGroupSide): void => {
       // Write only on change — the observer does not watch attributes (so a
       // stamp cannot re-trigger it), but a removed section's container may
       // be re-decided, and an unconditional set would still churn
@@ -99,7 +106,8 @@ export function installModelGroupSide(ctx: ClientContext): void {
         const text = headingTextOf(section, (id) => document.getElementById(id))
         rows.push({ section, containerKey: key, headingText: text ?? '' })
       }
-      const verdicts = classifyModelGroups(rows)
+      const activeRemoteServerId = document.documentElement.getAttribute(REMOTE_SERVER_ATTRIBUTE) ?? undefined
+      const verdicts = classifyModelGroupsForSession(rows, activeRemoteServerId)
       rows.forEach((row, i) => applyVerdict(row.section, verdicts[i]))
     }
 
@@ -115,6 +123,11 @@ export function installModelGroupSide(ctx: ClientContext): void {
       }
     })
     observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+    // MS-4: the session's server moves on <html> alone (A's session → B's
+    // with the menu open touches no group) — rescan synchronously, same
+    // no-rAF discipline as above.
+    const serverObserver = new MutationObserver(() => scan())
+    serverObserver.observe(document.documentElement, { attributes: true, attributeFilter: [REMOTE_SERVER_ATTRIBUTE] })
     // The initial paint may already hold groups (session restored under an
     // open menu): stamp them synchronously at install, like every observer
     // effect here does.
@@ -122,6 +135,7 @@ export function installModelGroupSide(ctx: ClientContext): void {
 
     return () => {
       observer.disconnect()
+      serverObserver.disconnect()
       // Undo every stamp so the host DOM reads exactly as before the effect
       // ran — the CSS rules key on the stamp, so this un-hides everything.
       for (const section of document.querySelectorAll(`${GROUP_SELECTOR}[${STAMP}]`)) {

package/src/client/effects/remote-session.ts

@@ -1,9 +1,10 @@
 import type { ClientContext, MobileSessionRow } from '../compat/types.ts'
 import { mainSessionIdOf } from '../compat/types.ts'
-import { isVirtual } from '../../virtual-id.ts'
+import { fromVirtual, isVirtual } from '../../virtual-id.ts'
 import { REMOTE_SESSION_CSS } from '../styles/remote-session.css.ts'
-import { BRIDGE_STAMP_ATTRIBUTE, BRIDGE_STAMP_PLUGIN, getRemoteStatusStore, shouldStampBridgeAttribute, subscribeIfVirtual } from '../../client-data/remote-status.ts'
+import { BRIDGE_STAMP_ATTRIBUTE, BRIDGE_STAMP_PLUGIN, getRemoteStatusStore, shouldStampBridgeForSession, subscribeIfVirtual } from '../../client-data/remote-status.ts'
 import { en, zh } from '../locales.ts'
+import { REMOTE_SERVER_ATTRIBUTE } from '../../client-data/model-group-side.ts'
 
 /**
  * The remote-session marker (T41b): the CURRENT main-view session id, read
@@ -14,6 +15,12 @@ import { en, zh } from '../locales.ts'
  * every open-on-the-server-machine entry, so the decision lives at the one
  * place that knows the session and never inside component DOM.
  *
+ * MS-4: with several servers paired, the virtual id's serverId half is
+ * stamped alongside as `data-zr-remote-server="<serverId>"` — the model
+ * menu's per-server isolation (effects/model-group-side.ts reads it to hide
+ * the OTHER paired servers' groups; remote-session.css.ts hides them). Both
+ * attributes move together: a local session (or unmount) clears both.
+ *
  * The official tie-break is kept verbatim: when the previous answer is still
  * mainView-retained it STAYS the answer, and only otherwise does the first
  * mainView-retained row in catalog order win — so two simultaneously
@@ -66,8 +73,14 @@ export function installRemoteSessionGuard(ctx: ClientContext): void {
     const apply = (): void => {
       const sessionId = currentMainSessionIdOf(ctx)
       const root = document.documentElement
-      if (sessionId !== undefined && isVirtual(sessionId)) root.setAttribute('data-zr-remote-session', '1')
-      else root.removeAttribute('data-zr-remote-session')
+      const parts = sessionId !== undefined ? fromVirtual(sessionId) : undefined
+      if (parts !== undefined) {
+        root.setAttribute('data-zr-remote-session', '1')
+        if (root.getAttribute(REMOTE_SERVER_ATTRIBUTE) !== parts.serverId) root.setAttribute(REMOTE_SERVER_ATTRIBUTE, parts.serverId)
+      } else {
+        root.removeAttribute('data-zr-remote-session')
+        root.removeAttribute(REMOTE_SERVER_ATTRIBUTE)
+      }
     }
     apply()
     const offs: Array<() => void> = [ctx.sessions.list.subscribe(apply)]
@@ -79,6 +92,7 @@ export function installRemoteSessionGuard(ctx: ClientContext): void {
     return () => {
       for (const off of offs) off()
       document.documentElement.removeAttribute('data-zr-remote-session')
+      document.documentElement.removeAttribute(REMOTE_SERVER_ATTRIBUTE)
     }
   }, 'dsh-zen-remote: remote-session attribute')
 
@@ -103,7 +117,7 @@ export function installRemoteSessionGuard(ctx: ClientContext): void {
     }
     const applyBridge = (): void => {
       const view = store.getSnapshot().view
-      if (shouldStampBridgeAttribute(view?.bridgedPlugins, BRIDGE_STAMP_PLUGIN)) {
+      if (shouldStampBridgeForSession(view, currentMainSessionIdOf(ctx), BRIDGE_STAMP_PLUGIN)) {
         root.setAttribute(BRIDGE_STAMP_ATTRIBUTE, '1')
         root.style.removeProperty('--zr-bridge-note')
       } else {
@@ -121,7 +135,13 @@ export function installRemoteSessionGuard(ctx: ClientContext): void {
         applyBridge()
         return
       }
-      if (!virtualNow && offStore !== undefined) {
+      // MS-6: remote A → remote B keeps the subscription, but the verdict
+      // belongs to the session's own server and must be re-judged.
+      if (virtualNow) {
+        applyBridge()
+        return
+      }
+      if (offStore !== undefined) {
         offStore()
         offStore = undefined
         clear()