dsh-zen-remote 2.3.10 → 2.4.0

package/src/client-routes.ts

@@ -40,6 +40,8 @@ import type { BridgeStatus } from './plugin-bridge.js'
 import { RELAY_HTTP_ROUTES } from './relay-access.js'
 import { relayCredentialsDigest, RelayError } from './relay-client.js'
 import type { RelayClient, RelayHttpResult } from './relay-client.js'
+import { MAX_PAIRED_SERVERS } from './relay-pool.js'
+import type { RelayPool, RelayPoolEntryView } from './relay-pool.js'
 import { resolveDshVersion } from './relay-server.js'
 import { fromVirtual } from './virtual-id.js'
 
@@ -105,6 +107,13 @@ export const CLIENT_UNSHARE_ROUTE = `${CLIENT_ROUTE_PREFIX}/unshare`
  * and re-judges the mergers immediately. */
 export const CLIENT_CURRENT_SESSION_ROUTE = `${CLIENT_ROUTE_PREFIX}/current-session`
 
+/** POST `{entryId?: string, all?: boolean}` (MS-5): remove one paired server
+ * by its entry id, or every paired server at once (`all: true`). The paired
+ * list lives in `zen-remote-state.json`; this route goes through the pool so
+ * the live clients stop with their records. Pool-mode only — a mount without
+ * a pool has no paired list to edit and answers the unknown-path 404. */
+export const CLIENT_UNPAIR_ROUTE = `${CLIENT_ROUTE_PREFIX}/unpair`
+
 /** Longest `sessionId` the current-session route accepts (T62): real ids —
  * a local `session-<uuid>` or a `zr~<serverId>~<id>` virtual id — are far
  * shorter; the cap bounds garbage, not reality. */
@@ -150,6 +159,21 @@ export interface ClientHandlerOptions {
    * never connected, so the settings page still gets a fresh answer while
    * the startup `connect()` is still unpaired. */
   getRelayClient?: () => RelayClient | undefined
+  /** MS-5 POOL mode: the multi-server relay pool. When present it REPLACES
+   * the row-driven single-client facts everywhere: the paired list (not the
+   * row's serverUrl/deviceToken) is the truth, claim pairs straight into the
+   * pool (the token never reaches the browser), unpair/reconnect address
+   * pool entries, and status / remote-status report the whole list (the
+   * top level keeps the FIRST entry's fields so the existing page keeps
+   * rendering). The single-`getRelayClient` form above stays exactly as it
+   * was for the old wiring and the tests. */
+  pool?: RelayPool
+  /** MS-5: the PB-2 bridge verdict for ONE pool entry, computed PER CALL off
+   * that entry's own handshake table and connection state — per-server
+   * isolation for the status / remote-status bodies. Undefined (old tests,
+   * the unwired host mount): every per-server `pluginBridge` / per-server
+   * `bridgedPlugins` list reads `[]`. */
+  getPluginBridgeStatusForServer?: (serverId: string | undefined, client: RelayClient) => BridgeStatus[]
   /** The typert interception's diagnostics (T23b-1), read live per request.
    * Shapes, counters and failure codes only — never a token. Undefined when
    * this composition never even attempted an install (no typertGateway). */
@@ -184,7 +208,9 @@ export interface ClientHandlerOptions {
    * mount's remoteStatusOnly wall 404s the route before this matters, and
    * a client handler WITHOUT the sink answers the same 404 (no sink, no
    * route). */
-  onCurrentSession?: (read: CurrentSessionRead) => void
+  onCurrentSession?: (read: CurrentSessionRead, reportedLang?: 'zh' | 'en') => void
+  /** Language for route error messages (`'zh'` default, `'en'` English). */
+  lang?: 'zh' | 'en' | (() => 'zh' | 'en') | undefined
   /** CU-3, the debug-report route's inputs — all optional; the route answers
    * its 404-shaped refusal without them (an unwired composition must not
    * pretend to have diagnostics). Wired on BOTH role mounts.
@@ -424,28 +450,24 @@ function remoteStatusStateOf(relay: RelayClient | undefined): 'online' | 'offlin
 }
 
 /**
- * The status route's body, computed exactly as the CLIENT_STATUS_ROUTE
- * branch always has — extracted (CU-3) so the debug-report route can embed
- * the same diagnostics aggregation without a second implementation. All
- * reads are live per call: volatile row fields, the interception getters,
- * the relay client's current state. May await one bounded probe or connect
- * (never longer than the probe timeout).
+ * The diagnostics decorator shared by the single-client and pool status
+ * bodies (CU-3's extraction, extended by MS-5): every interception getter is
+ * read live per call, and the compat verdict rides whenever there is
+ * something to report — from `compatRelay`'s last handshake (the single
+ * client, or in pool mode the FIRST entry's client) or from the interceptor's
+ * incompatible-call ring. `pluginBridgeOverride` replaces the single-client
+ * verdict source in pool mode (the first entry's per-server verdicts, keeping
+ * the top-level field's shape).
  */
-async function statusBodyOf(options: ClientHandlerOptions): Promise<Record<string, unknown>> {
-  const fetchImpl: FetchLike = options.fetchImpl ?? ((url, init) => fetch(url, init))
-  // The typert interception's view (T23b-1) rides on EVERY status
-  // answer, whatever the connection state — the settings surface needs
-  // it to explain a refused install even while unpaired. The interface
-  // compat verdict (T42) appears once there is something to report: a
-  // stored comparison from the relay client's last handshake, or any
-  // incompatible call the interceptor recorded. Absent otherwise —
-  // nothing to show, and the settings block presence-gates on exactly
-  // that.
+function diagnosticsDecorator(
+  options: ClientHandlerOptions,
+  compatRelay: RelayClient | undefined,
+  pluginBridgeOverride?: BridgeStatus[],
+): (body: Record<string, unknown>) => Record<string, unknown> {
   const intercept = options.getIntercept?.()
   const fetchRouteIntercept = options.getFetchRouteIntercept?.()
   const serviceProbe = options.getServiceProbe?.()
   const pluginRouteIntercept = options.getPluginRouteIntercept?.()
-  const compatRelay = options.getRelayClient?.()
   const compat =
     compatRelay?.compat !== undefined || (intercept?.incompatibleCalls.length ?? 0) > 0
       ? {
@@ -455,17 +477,97 @@ async function statusBodyOf(options: ClientHandlerOptions): Promise<Record<strin
           incompatibleCalls: intercept?.incompatibleCalls ?? [],
         }
       : undefined
-  const withDiagnostics = (body: Record<string, unknown>): Record<string, unknown> => {
+  return (body: Record<string, unknown>): Record<string, unknown> => {
     // PB-2: the per-plugin bridge verdict rides EVERY status answer —
     // the settings surface explains a not-bridged plugin whatever the
     // connection state (unpaired reads all-offline, the honest verdict).
-    let next: Record<string, unknown> = { ...body, pluginBridge: options.getPluginBridgeStatus?.() ?? [] }
+    let next: Record<string, unknown> = { ...body, pluginBridge: pluginBridgeOverride ?? options.getPluginBridgeStatus?.() ?? [] }
     if (intercept !== undefined) next = { ...next, intercept }
     if (fetchRouteIntercept !== undefined) next = { ...next, fetchRouteIntercept }
     if (serviceProbe !== undefined) next = { ...next, serviceProbe }
     if (pluginRouteIntercept !== undefined) next = { ...next, pluginRouteIntercept }
     return compat === undefined ? next : { ...next, compat }
   }
+}
+
+/**
+ * One pool entry's per-server status row (MS-5): the live client facts and
+ * the entry's own identity — NEVER the token, which the route never even
+ * sees (it lives in the state file, behind the pool). `compat` appears only
+ * once that client has a handshake verdict to report; `pluginBridge` comes
+ * from the per-server verdict getter ([] unwired).
+ */
+function poolServerStatus(entry: RelayPoolEntryView, options: ClientHandlerOptions): Record<string, unknown> {
+  const client = entry.client
+  const body: Record<string, unknown> = {
+    entryId: entry.entryId,
+    serverId: entry.serverId,
+    serverUrl: entry.serverUrl,
+    serverName: entry.serverName ?? '',
+    displayName: entry.displayName,
+    state: client.state,
+    nextRetryAt: client.nextRetryAt ?? null,
+    ...(client.lastError !== undefined ? { lastError: client.lastError } : {}),
+    ...(client.compat !== undefined
+      ? { compat: { identical: client.compat.identical, different: client.compat.different, unavailable: client.compat.unavailable } }
+      : {}),
+    pluginBridge: options.getPluginBridgeStatusForServer?.(entry.serverId, client) ?? [],
+  }
+  return body
+}
+
+/**
+ * The POOL status body (MS-5): the paired list is the truth — the row's
+ * serverUrl/deviceToken are never consulted. The top level keeps the FIRST
+ * entry's compatibility fields (the old single-server page keeps rendering)
+ * and every entry reports as one `servers` row; `maxServers` names the cap.
+ * An empty pool answers `unpaired` — the honest "nothing paired".
+ */
+async function poolStatusBodyOf(options: ClientHandlerOptions): Promise<Record<string, unknown>> {
+  const pool = options.pool as RelayPool
+  const entries = pool.entries()
+  const first = entries[0]
+  const bridgeOverride = first !== undefined
+    ? options.getPluginBridgeStatusForServer?.(first.serverId, first.client) ?? []
+    : []
+  const withDiagnostics = diagnosticsDecorator(options, first?.client, bridgeOverride)
+  const servers = entries.map((entry) => poolServerStatus(entry, options))
+  if (first === undefined) {
+    return withDiagnostics({ state: 'unpaired', maxServers: MAX_PAIRED_SERVERS, servers })
+  }
+  const body = deviceStatusBody(
+    first.client.state,
+    { serverName: first.serverName ?? '', deviceName: first.client.handshakeInfo?.deviceName },
+    first.serverUrl,
+    first.client.deviceNameSyncing,
+  )
+  if (first.client.nextRetryAt !== null && first.client.nextRetryAt !== undefined) body.nextRetryAt = first.client.nextRetryAt
+  if (first.client.lastError !== undefined) body.lastError = first.client.lastError
+  return withDiagnostics({ ...body, maxServers: MAX_PAIRED_SERVERS, servers })
+}
+
+/**
+ * The status route's body, computed exactly as the CLIENT_STATUS_ROUTE
+ * branch always has — extracted (CU-3) so the debug-report route can embed
+ * the same diagnostics aggregation without a second implementation. All
+ * reads are live per call: volatile row fields, the interception getters,
+ * the relay client's current state. May await one bounded probe or connect
+ * (never longer than the probe timeout). In pool mode the paired list is
+ * the truth instead ({@link poolStatusBodyOf}); the row is not consulted.
+ */
+async function statusBodyOf(options: ClientHandlerOptions): Promise<Record<string, unknown>> {
+  const fetchImpl: FetchLike = options.fetchImpl ?? ((url, init) => fetch(url, init))
+  if (options.pool !== undefined) return poolStatusBodyOf(options)
+  // The typert interception's view (T23b-1) rides on EVERY status
+  // answer, whatever the connection state — the settings surface needs
+  // it to explain a refused install even while unpaired. The interface
+  // compat verdict (T42) appears once there is something to report: a
+  // stored comparison from the relay client's last handshake, or any
+  // incompatible call the interceptor recorded. Absent otherwise —
+  // nothing to show, and the settings block presence-gates on exactly
+  // that.
+  const compatRelay = options.getRelayClient?.()
+  const withDiagnostics = diagnosticsDecorator(options, compatRelay)
   // The ROW decides its own two shapes first, per request (both fields
   // are volatile { get() } wrappers — only the row object apply()
   // received is a live source): without both credentials nothing is
@@ -527,6 +629,12 @@ async function statusBodyOf(options: ClientHandlerOptions): Promise<Record<strin
  */
 export function createClientHandler(options: ClientHandlerOptions): ClientHandler {
   const fetchImpl: FetchLike = options.fetchImpl ?? ((url, init) => fetch(url, init))
+  const resolveLang = (): 'zh' | 'en' => {
+    const value = typeof options.lang === 'function' ? options.lang() : options.lang
+    return value === 'en' ? 'en' : 'zh'
+  }
+  const mismatchMessage = (): string =>
+    resolveLang() === 'en' ? 'This remote session belongs to another server' : '此远程会话属于其他主服务端'
   return async (req, res) => {
     // Wall 1: DSH's own admission, relaying its refusal verbatim.
     const admission = options.admit(req)
@@ -549,7 +657,10 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
       if (route === CLIENT_DEBUG_REPORT_ROUTE && req.headers['x-zen-remote-via'] !== undefined) {
         responseJson(res, 403, {
           ok: false,
-          error: { code: 'via-gateway', message: '诊断报告只能在本机导出' },
+          error: {
+            code: 'via-gateway',
+            message: resolveLang() === 'en' ? 'Diagnostics report can only be exported on this machine' : '诊断报告只能在本机导出',
+          },
         })
         return
       }
@@ -580,6 +691,23 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           responseJson(res, 400, { ok: false, code: normalized.reason })
           return
         }
+        // MS-5 pool mode: the 8-server cap is judged BEFORE the pairing
+        // round-trip — a refusal the user can fix locally (remove a server,
+        // or re-enter an already-paired address) must not spend a claim code
+        // on the wire. An address that is ALREADY paired is always allowed
+        // through: re-pairing it just refreshes the token in place, at 8/8
+        // too. The pool stays the single writer afterwards: the gateway's
+        // token goes straight into `zen-remote-state.json` and NEVER reaches
+        // the browser — this response carries only the entry id and the
+        // address echo.
+        const pool = options.pool
+        if (pool !== undefined) {
+          const known = pool.entries().some((entry) => entry.serverUrl === normalized.url)
+          if (!known && pool.entries().length >= MAX_PAIRED_SERVERS) {
+            responseJson(res, 409, { ok: false, code: 'limit-reached' })
+            return
+          }
+        }
         const payload = JSON.stringify({
           code: stringOrEmpty(body.code),
           name: stringOrEmpty(body.name),
@@ -614,7 +742,68 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           responseJson(res, 502, { ok: false, code: 'unreachable' })
           return
         }
-        respondClaim(res, classifyClaimResponse(status, gatewayBody), normalized.url)
+        const outcome = classifyClaimResponse(status, gatewayBody)
+        if (pool === undefined || !outcome.ok) {
+          respondClaim(res, outcome, normalized.url)
+          return
+        }
+        // Pool mode, redemption succeeded: land the pairing in the state
+        // file through the pool (which also starts/refreshes the live
+        // client) and answer without the token. The pair() can only refuse
+        // past the pre-check on a concurrent writer — the same envelopes.
+        const paired = await pool.pair({
+          serverUrl: normalized.url,
+          token: outcome.token,
+          deviceId: outcome.deviceId,
+          deviceName: outcome.deviceName,
+        })
+        if (!paired.ok) {
+          responseJson(res, paired.code === 'limit-reached' ? 409 : 400, { ok: false, code: paired.code })
+          return
+        }
+        responseJson(res, 200, {
+          ok: true,
+          entryId: paired.entry.entryId,
+          deviceId: outcome.deviceId,
+          deviceName: outcome.deviceName,
+          serverUrl: normalized.url,
+        })
+        return
+      }
+      if (route === CLIENT_UNPAIR_ROUTE) {
+        // MS-5: remove one paired server or all of them. Pool-mode only —
+        // a mount without a pool has no paired list to edit (the old
+        // single-server pairing lived in the ROW, which the browser writes
+        // directly), and answers the same 404 an unknown path would.
+        const pool = options.pool
+        if (pool === undefined) {
+          responseJson(res, 404, { ok: false, error: { code: 'not-found', message: 'Unknown client route' } })
+          return
+        }
+        if (method !== 'POST') {
+          res.setHeader('Allow', 'POST')
+          responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use POST' } })
+          return
+        }
+        if (!sameOriginPost(req)) {
+          responseJson(res, 403, {
+            ok: false,
+            error: { code: 'origin-rejected', message: 'The request must originate from this DSH Web application' },
+          })
+          return
+        }
+        const body = await readJsonBody(req)
+        if (body.all === true) {
+          const removed = pool.unpairAll()
+          responseJson(res, 200, { ok: true, removed })
+          return
+        }
+        if (typeof body.entryId === 'string' && body.entryId !== '') {
+          const removed = pool.unpair(body.entryId)
+          responseJson(res, 200, { ok: true, removed: removed ? 1 : 0 })
+          return
+        }
+        responseJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'entryId (non-empty string) or all (true) is required' } })
         return
       }
       if (route === CLIENT_STATUS_ROUTE) {
@@ -672,6 +861,8 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
             pushSummary: values.pushSummary,
             pushTurnEnd: values.pushTurnEnd,
             pushTool: values.pushTool,
+            pushEnabled: values.pushEnabled,
+            pushSessionName: values.pushSessionName,
             serverUrl: stringOrEmpty(unwrapVolatile(record.serverUrl)).trim(),
           },
           statusBody: await statusBodyOf(options),
@@ -696,6 +887,31 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           return
         }
         const relay = options.getRelayClient?.()
+        // MS-5 pool mode: an optional { entryId } names ONE server — the
+        // same offline-only, 409-on-conflict contract the single client's
+        // button has, per entry; without it every OFFLINE server gets one
+        // attempt (an online server is not "reconnected", it is fine).
+        const pool = options.pool
+        if (pool !== undefined) {
+          const body = await readJsonBody(req)
+          const entryId = typeof body.entryId === 'string' && body.entryId !== '' ? body.entryId : undefined
+          if (entryId === undefined) {
+            const started = await pool.reconnect()
+            responseJson(res, 200, { ok: true, started })
+            return
+          }
+          const entry = pool.getByEntryId(entryId)
+          if (entry === undefined) {
+            responseJson(res, 404, { ok: false, error: { code: 'not-found', message: 'No such paired server' } })
+            return
+          }
+          if (entry.client.state !== 'offline' || !entry.client.reconnect()) {
+            responseJson(res, 409, { ok: false, error: { code: 'not-offline', message: 'The client is not offline' } })
+            return
+          }
+          responseJson(res, 200, { ok: true })
+          return
+        }
         // No relay client (a composition that never built one): there is
         // nothing to reconnect, and the probe-shaped status route is the
         // only connection surface this deployment has.
@@ -729,6 +945,16 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           return
         }
         const relay = options.getRelayClient?.()
+        // MS-5 pool mode: the same QUESTION per server — one authenticated
+        // ping sweep over the offline clients, the reachable ones get the
+        // controlled `networkRestored()` (probe-first, no storm, offline
+        // only — the pool method enforces the same rules per client).
+        const pool = options.pool
+        if (pool !== undefined) {
+          const outcome = await pool.probeAndRestoreAll()
+          responseJson(res, 200, { ok: true, reachable: outcome.reachable, reconnected: outcome.reconnected })
+          return
+        }
         if (relay === undefined) {
           responseJson(res, 503, { ok: false, error: { code: 'unavailable', message: 'No relay client is running' } })
           return
@@ -762,8 +988,41 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
         // sort is pinned here so the field's shape never depends on the
         // registry's internal order). The host mount — no verdict source —
         // answers [].
-        const relay = options.getRelayClient?.()
+        // MS-5 pool mode: the SAME shape per server, under `servers` keyed
+        // by the handshake serverId (an entry that never handshook owns no
+        // virtual ids and is not addressable — skipped). The top level
+        // mirrors the FIRST entry so the old page keeps rendering.
+        const pool = options.pool
         const intercept = options.getIntercept?.()
+        const bridgedOf = (serverId: string | undefined, client: RelayClient): string[] =>
+          (options.getPluginBridgeStatusForServer?.(serverId, client) ?? [])
+            .filter((status) => status.bridged)
+            .map((status) => status.plugin)
+            .sort()
+        if (pool !== undefined) {
+          const entries = pool.entries()
+          const first = entries[0]
+          const servers: Record<string, Record<string, unknown>> = {}
+          for (const entry of entries) {
+            if (entry.serverId === undefined) continue
+            servers[entry.serverId] = {
+              state: remoteStatusStateOf(entry.client),
+              versionMismatch: (entry.client.compat?.different?.length ?? 0) > 0,
+              serverName: entry.serverName ?? '',
+              bridgedPlugins: bridgedOf(entry.serverId, entry.client),
+            }
+          }
+          responseJson(res, 200, {
+            state: remoteStatusStateOf(first?.client),
+            versionMismatch: (first?.client.compat?.different?.length ?? 0) > 0,
+            serverName: first?.serverName ?? '',
+            closed: Object.fromEntries((intercept?.closedSessions ?? []).map((record) => [record.sessionId, record.reason])),
+            bridgedPlugins: first !== undefined ? bridgedOf(first.serverId, first.client) : [],
+            servers,
+          })
+          return
+        }
+        const relay = options.getRelayClient?.()
         responseJson(res, 200, {
           state: remoteStatusStateOf(relay),
           versionMismatch: (relay?.compat?.different?.length ?? 0) > 0,
@@ -807,7 +1066,8 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           return
         }
         const read: CurrentSessionRead = raw === null ? { kind: 'none' } : { kind: 'open', sessionId: raw }
-        sink(read)
+        const reportedLang = body.lang === 'en' ? ('en' as const) : body.lang === 'zh' ? ('zh' as const) : undefined
+        sink(read, reportedLang)
         responseJson(res, 200, { ok: true })
         return
       }
@@ -832,6 +1092,25 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           responseJson(res, 400, { ok: false, error: { code: 'not-virtual', message: 'sessionId must be a remote (virtual) session id' } })
           return
         }
+        // MS-5 pool mode: the id's serverId half names the server — its own
+        // client closes the session with the ORIGINAL id. A server the pool
+        // does not hold is the same remote-mismatch the interceptor answers.
+        const pool = options.pool
+        if (pool !== undefined) {
+          const entry = pool.getByServerId(parts.serverId)
+          if (entry === undefined) {
+            responseJson(res, 200, { ok: false, error: { code: 'remote-mismatch', message: mismatchMessage() } })
+            return
+          }
+          try {
+            await entry.client.unshare(parts.id)
+            responseJson(res, 200, { ok: true })
+          } catch (error) {
+            const code = error instanceof RelayError ? error.code : 'internal'
+            responseJson(res, 200, { ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } })
+          }
+          return
+        }
         const relay = options.getRelayClient?.()
         if (relay === undefined) {
           responseJson(res, 503, { ok: false, error: { code: 'unavailable', message: 'No relay client is running' } })
@@ -841,7 +1120,7 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
         // just answer not-shared out there — the mismatch is answerable
         // locally, with the code the interceptor uses for the same fact.
         if (relay.handshakeInfo === undefined || relay.handshakeInfo.serverId !== parts.serverId) {
-          responseJson(res, 200, { ok: false, error: { code: 'remote-mismatch', message: '此远程会话属于其他主服务端' } })
+          responseJson(res, 200, { ok: false, error: { code: 'remote-mismatch', message: mismatchMessage() } })
           return
         }
         try {
@@ -888,13 +1167,42 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           responseJson(res, 400, { ok: false, error: { code: 'not-virtual', message: 'sessionId is not a remote session id' } })
           return
         }
+        // MS-5 pool mode: route by the id's serverId half. A server the pool
+        // does not hold refuses like a foreign one; its client must be the
+        // ONLINE one before the query travels with the original id restored.
+        const pool = options.pool
+        if (pool !== undefined) {
+          const entry = pool.getByServerId(parts.serverId)
+          if (entry === undefined) {
+            responseJson(res, 400, { ok: false, error: { code: 'remote-mismatch', message: mismatchMessage() } })
+            return
+          }
+          if (entry.client.state !== 'online') {
+            responseJson(res, 503, { ok: false, error: { code: 'remote-offline' } })
+            return
+          }
+          url.searchParams.set('sessionId', parts.id)
+          // A browser walk-off cancels the round-trip mid-flight; the write
+          // guard in the catch keeps a settled answer from racing the close.
+          const hangUp = new AbortController()
+          res.once('close', () => {
+            if (!res.writableEnded) hangUp.abort()
+          })
+          try {
+            const result = await entry.client.http(httpRoute, url.searchParams.toString(), hangUp.signal)
+            respondUpstream(res, result)
+          } catch (error) {
+            if (!res.writableEnded && !res.destroyed) respondRelayFailure(res, error)
+          }
+          return
+        }
         const relay = options.getRelayClient?.()
         if (relay === undefined || relay.state !== 'online') {
           responseJson(res, 503, { ok: false, error: { code: 'remote-offline' } })
           return
         }
         if (relay.handshakeInfo?.serverId !== parts.serverId) {
-          responseJson(res, 400, { ok: false, error: { code: 'remote-mismatch', message: '此远程会话属于其他主服务端' } })
+          responseJson(res, 400, { ok: false, error: { code: 'remote-mismatch', message: mismatchMessage() } })
           return
         }
         url.searchParams.set('sessionId', parts.id)

package/src/config.ts

@@ -41,9 +41,11 @@ const SERVER_NAME_MAX = 40
 
 /** The effective configuration one resolved value set, defaults included. */
 export interface ZenRemoteConfig {
-  /** Which half of the plugin runs in this DSH process; anything the layers
-   * leave unresolved means `'host'` (see {@link resolveRole}). */
-  role: 'host' | 'client'
+  /** Which half of the plugin runs in this DSH process. `'host'` serves the
+   * gateway and never dials out; `'client'` dials one server and serves no
+   * gateway; `'peer'` (MS Phase 2) does both. Anything the layers leave
+   * unresolved means `'host'` (see {@link resolveRole}). */
+  role: 'host' | 'client' | 'peer'
   /** Port the gateway child listens on. */
   port: number
   /** Bind address of the gateway child. */
@@ -69,6 +71,12 @@ export interface ZenRemoteConfig {
   pushTurnEnd: boolean
   /** Register the model-facing `push_notify` tool. */
   pushTool: boolean
+  /** Master switch for session notifications: when false, disables all push
+   * listeners and does not register push_notify. */
+  pushEnabled: boolean
+  /** Include the source session name on the first line of push notification
+   * bodies. */
+  pushSessionName: boolean
   /** Server display name, at most {@link SERVER_NAME_MAX} characters. */
   serverName: string
   /** Idle-sleep window of a remote-enabled session: after this many hours
@@ -120,6 +128,8 @@ export const DEFAULTS: ZenRemoteConfig = {
   pushSummary: false,
   pushTurnEnd: false,
   pushTool: true,
+  pushEnabled: true,
+  pushSessionName: false,
   serverName: defaultServerName(),
   idleHours: 48,
   autoShareNewSessions: false,
@@ -335,7 +345,7 @@ interface FieldResolver<T> {
 }
 
 const FIELDS: { [K in keyof ZenRemoteConfig]: FieldResolver<ZenRemoteConfig[K]> } = {
-  role: { row: oneOf('host', 'client'), file: oneOf('host', 'client') },
+  role: { row: oneOf('host', 'client', 'peer'), file: oneOf('host', 'client', 'peer') },
   port: { env: envNumber('LAN_GATE_PORT', intIn(1, 65535)), row: intIn(1, 65535), file: lenientFileNumber(intIn(1, 65535)) },
   host: { env: envString('LAN_GATE_HOST'), row: nonEmptyString, file: nonEmptyString },
   targetPort: { env: envNumber('LAN_GATE_TARGET_PORT', intIn(1, 65535)), row: intIn(1, 65535) },
@@ -348,6 +358,12 @@ const FIELDS: { [K in keyof ZenRemoteConfig]: FieldResolver<ZenRemoteConfig[K]>
   pushSummary: { env: envBool('DSH_PUSH_SUMMARY', (raw) => raw === '1'), row: boolLike, file: boolLike },
   pushTurnEnd: { env: envBool('DSH_PUSH_TURN_END', (raw) => raw === '1'), row: boolLike, file: boolLike },
   pushTool: { env: envBool('DSH_PUSH_TOOL', (raw) => raw !== '0'), row: boolLike, file: boolLike },
+  // The master switch copies pushTool's env shape (default on, only the exact
+  // '0' flips it off); the session-name line copies pushSummary's (default
+  // off, '1' turns it on). Both restart the push leg because apply() wires
+  // its listeners from them (P55-1) — hence the RESTART_FIELDS entries.
+  pushEnabled: { env: envBool('DSH_PUSH_ENABLED', (raw) => raw !== '0'), row: boolLike, file: boolLike },
+  pushSessionName: { env: envBool('DSH_PUSH_SESSION_NAME', (raw) => raw === '1'), row: boolLike, file: boolLike },
   serverName: { row: serverNameOf, file: serverNameOf },
   idleHours: { row: inRange(0, 8760), file: inRange(0, 8760) },
   autoShareNewSessions: { row: boolLike, file: boolLike },
@@ -444,6 +460,8 @@ export function resolveConfig(
     pushSummary: resolveField('pushSummary', safeRow, safeFile, env, sources),
     pushTurnEnd: resolveField('pushTurnEnd', safeRow, safeFile, env, sources),
     pushTool: resolveField('pushTool', safeRow, safeFile, env, sources),
+    pushEnabled: resolveField('pushEnabled', safeRow, safeFile, env, sources),
+    pushSessionName: resolveField('pushSessionName', safeRow, safeFile, env, sources),
     serverName: resolveField('serverName', safeRow, safeFile, env, sources),
     idleHours: resolveField('idleHours', safeRow, safeFile, env, sources),
     autoShareNewSessions: resolveField('autoShareNewSessions', safeRow, safeFile, env, sources),
@@ -475,19 +493,42 @@ export function readFileConfig(env: NodeJS.ProcessEnv = process.env): Record<str
 }
 
 /**
- * The normalized role behind a row's `role` knob. Anything but the exact
- * string `'client'` means host, so a typo degrades to the full plugin rather
- * than silently dropping the gateway and push halves. The value is read
- * through {@link unwrapVolatile} first: since T17 every row field arrives as
- * a `{ get() }` live reference, and comparing the wrapper itself against
- * `'client'` would always answer host (T17b). Resolution-order note:
- * {@link resolveConfig} validates each layer against the two-member enum
- * first, so an invalid row role can still be rescued by the file layer; this
- * function answers the final merged value. Kept on the main entry's export
- * surface for test/role-wiring.test.cjs.
+ * The normalized role behind a row's `role` knob. Only the exact strings
+ * `'client'` and `'peer'` mean those roles — everything else degrades to
+ * host, so a typo runs the full plugin rather than silently dropping the
+ * gateway and push halves. The value is read through {@link unwrapVolatile}
+ * first: since T17 every row field arrives as a `{ get() }` live reference,
+ * and comparing the wrapper itself against a role string would always answer
+ * host (T17b). Resolution-order note: {@link resolveConfig} validates each
+ * layer against the enum first, so an invalid row role can still be rescued
+ * by the file layer; this function answers the final merged value. Kept on
+ * the main entry's export surface for test/role-wiring.test.cjs.
  */
-export function resolveRole(row: unknown): 'host' | 'client' {
-  return unwrapVolatile((row as { role?: unknown } | null | undefined)?.role) === 'client' ? 'client' : 'host'
+export function resolveRole(row: unknown): 'host' | 'client' | 'peer' {
+  const value = unwrapVolatile((row as { role?: unknown } | null | undefined)?.role)
+  if (value === 'client') return 'client'
+  if (value === 'peer') return 'peer'
+  return 'host'
+}
+
+/**
+ * Whether the role serves remote access to OTHER machines: host and peer do
+ * (the gateway, relay and push halves mount), a pure client does not. The
+ * role-gate the wiring reads INSTEAD of a `=== 'host'` compare, so a peer
+ * deploy gets the serving halves without every call site growing a third
+ * branch (MS Phase 2 wires it through).
+ */
+export function servesRole(role: 'host' | 'client' | 'peer'): boolean {
+  return role !== 'client'
+}
+
+/**
+ * Whether the role dials OUT to paired servers: client and peer do (the
+ * relay client / pool), a pure host has nothing to dial. {@link servesRole}'s
+ * counterpart.
+ */
+export function connectsRole(role: 'host' | 'client' | 'peer'): boolean {
+  return role !== 'host'
 }
 
 /**
@@ -536,6 +577,11 @@ export const Config = z.object({
   pushSummary: z.any().volatile(),
   pushTurnEnd: z.any().volatile(),
   pushTool: z.any().volatile(),
+  // Push-leg master switch and session-name line (P55-1): apply() wires its
+  // listeners and the push_notify tool from them, so both reload the row on
+  // change (RESTART_FIELDS).
+  pushEnabled: z.any().volatile(),
+  pushSessionName: z.any().volatile(),
   serverName: z.any().volatile(),
   idleHours: z.any().volatile(),
   autoShareNewSessions: z.any().volatile(),