dsh-zen-remote 2.3.11 → 2.4.1

package/src/index.ts

@@ -39,20 +39,21 @@ declare module '@deepseek-ai/cordis' {
     'loader/volatile-update'(paths: string[][]): void
   }
 }
-import { readFileConfig, resolveConfig, unwrapVolatile } from './config.js'
+import { readFileConfig, resolveConfig, unwrapVolatile, servesRole, connectsRole } from './config.js'
 import { createActivityTracker, createParentIndex, seedParentIndexFromSnapshots, startSweeper, type PersistedSessionSnapshot } from './activity.js'
 import { ADMIN_ROUTE_PREFIX, createAdminHandler } from './admin-routes.js'
-import type { SessionQueryLike } from './admin-routes.js'
-import { normalizedRowServerUrl } from './client-pairing.js'
+import type { AdminHandlerOptions, SessionQueryLike } from './admin-routes.js'
 import { CLIENT_ROUTE_PREFIX, createClientHandler } from './client-routes.js'
 import { responseJson, sameOriginPost } from './http.js'
-import { onSessionCreated, restoreBusy } from './share-ops.js'
-import type { AgentStatusLike } from './share-ops.js'
+import { isBlankSession, isFirstTurnStart, onSessionCreated, restoreBusy } from './share-ops.js'
+import type { AgentStatusLike, TurnBoundaryLike } from './share-ops.js'
 import type { AdminAdmission } from './admin-routes.js'
 import { startRestartWatcher } from './restart-watcher.js'
 import { handleShareExport, SHARE_EXPORT_ROUTE } from './share-export.js'
 import { createShareStore } from './share-store.js'
-import { createRelayClient, RelayError, volatileUpdateTouchesServerName } from './relay-client.js'
+import { createRelayPool } from './relay-pool.js'
+import type { RelayPool } from './relay-pool.js'
+import { volatileUpdateTouchesServerName } from './relay-client.js'
 import type { RelayClient } from './relay-client.js'
 import { computeFingerprints } from './fingerprint.js'
 import { runSelfCheck, installIntercept } from './intercept.js'
@@ -76,6 +77,7 @@ import { createRelayHandler, loadServerId, RELAY_PREFIX, resolveDshVersion } fro
 import type { RelayGateway, RelayHandler } from './relay-server.js'
 import { createBridgeRegistry, compareBridges } from './plugin-bridge.js'
 import { createWizardHandler, WIZARD_ROUTE_PREFIX } from './wizard/routes.js'
+import type { WizardHandlerOptions } from './wizard/routes.js'
 import { createCaddyManager } from './wizard/caddy-process.js'
 import type { SubprocessServiceLike } from './wizard/caddy-process.js'
 import { cfTokenConfigured, deleteCfTokenFile, readCfTokenFile, writeCfTokenFile } from './wizard/token-store.js'
@@ -89,6 +91,9 @@ import { createPluginLoopback } from './plugin-loopback.js'
 import { createPluginTunnel } from './plugin-tunnel.js'
 import { createLogRing, createPluginLog } from './log-ring.js'
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload-limits.js'
+import { applyUnshadowedRowKeys, clearUnshadowedRowKeys, writeCliConfig } from './cli/config-writer.js'
+import { acquireCliIpcServer } from './cli/ipc-server.js'
+import type { CliIpcDelegate, CliRouteHandler } from './cli/ipc-server.js'
 
 // The plugin bridge's public types (PB-1), re-exported so another plugin's
 // author can `import type { … } from 'dsh-zen-remote'` without reaching into
@@ -100,7 +105,7 @@ export type { BridgeDeclaration, ZenRemoteService } from './plugin-bridge.js'
 // plugin row's public surface stays on the main entry. The same-origin gate
 // moved to src/http.ts next to the response envelope (T14) but its export
 // stays here for scripts/check-upload-endpoint.mjs.
-export { Config, resolveRole } from './config.js'
+export { Config, resolveRole, servesRole, connectsRole } from './config.js'
 export { sameOriginPost } from './http.js'
 
 // The two sub-plugin entries the host role loads. They ship as plain .mjs at
@@ -170,11 +175,30 @@ const MAX_COLLISION_TRIES = 100
  */
 let clientRelayClient: RelayClient | undefined
 
-/** The live client-role relay client, if one was built. */
+/** The live client-role relay client, if one was built. MS-5: the wiring no
+ * longer builds one — the relay POOL below replaced it — so this stays
+ * undefined in production compositions; the getter (and the client-routes
+ * option of the same shape) remain for the single-client contract's old
+ * consumers and tests. */
 export function getRelayClient(): RelayClient | undefined {
   return clientRelayClient
 }
 
+/**
+ * The client role's relay pool (MS-5), created inside apply() and kept on
+ * the module so the debug-report wiring or a later half can reach it without
+ * reaching into a context. Undefined on a pure host role (and in
+ * compositions that never ran this module's apply), and — identity-guarded
+ * in the disposal effect — after the row that owned a pool was unloaded or
+ * reloaded (the T23a-fix discipline the relay client's slot always followed).
+ */
+let clientRelayPool: RelayPool | undefined
+
+/** The live client-role relay pool, if one was built. */
+export function getRelayPool(): RelayPool | undefined {
+  return clientRelayPool
+}
+
 /**
  * The plugin bridge's declaration registry (PB-1), created inside apply() on
  * BOTH roles and kept on the module so later tasks (the handshake's plugins
@@ -551,6 +575,8 @@ export async function handleUpload(
  *   request.
  */
 export function apply(ctx: Context, config: MobileNavConfig = {}): void {
+  const initialHome = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  applyUnshadowedRowKeys(initialHome, config as Record<string, unknown>)
   // CU-1: the plugin's own log ring (SPEC 方案 C) — rebuilt per apply, so a
   // row reload clears it (expected: the report describes THIS process
   // generation). `logWarn` / `logInfo` are the branch-shared double-writers:
@@ -735,10 +761,42 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       return undefined
     }
   }
-  if (effective.values.role === 'host') {
+  // MS-5: the two role halves are INDEPENDENT branches now, not an either/or
+  // — a future 'peer' deploy (servesRole AND connectsRole both true) runs
+  // both; host runs only the serving half; client only the dialing half.
+  // CLI-1: the row-scoped pieces the CLI IPC delegate forwards to. The role
+  // branches fill the slots they own; the restart-watcher effect at the
+  // bottom hands them to acquireCliIpcServer as ONE delegate, whose release
+  // rides the same effect (role-wiring pins the top-level effect counts, so
+  // the IPC lifecycle may not register its own).
+  const noopAdmit: (req: IncomingMessage) => AdminAdmission = () => ({ peer: {} })
+  const reflectNow = (): { get(name: string): unknown } | undefined =>
+    (ctx as Context & { reflect?: { get(name: string): unknown } }).reflect
+  let cliWizardHandler: CliRouteHandler | undefined
+  let cliAdminHandler: CliRouteHandler | undefined
+  let cliClientHandler: CliRouteHandler | undefined
+  let reportedBrowserLang: 'zh' | 'en' | undefined
+  const resolveActiveLang = (): 'zh' | 'en' => {
+    const cfg = resolveConfig(config, readFileConfig(), process.env).values.lang
+    if (cfg === 'en') return 'en'
+    if (cfg === 'zh') return 'zh'
+    if (reportedBrowserLang !== undefined) return reportedBrowserLang
+    return 'zh'
+  }
+  /** The managed ingress children THIS row generation owns (host branch
+   * only): the restart-watcher disposer stops them, which is the ONLY stop
+   * on compositions without a webServer (there the wizard effect — the
+   * historic owner of the stop — never fires). */
+  const cliManagedChildren: Array<{ stop(): void }> = []
+  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+  if (servesRole(effective.values.role)) {
     // A row that switched from client to host must not leave a stale relay
-    // client where getRelayClient() can find it (T23a-fix).
+    // client where getRelayClient() can find it (T23a-fix) — and no stale
+    // pool either where getRelayPool() can (MS-5; a peer row rebuilds its
+    // pool right after, this block having only cleared the previous
+    // generation's slot).
     clientRelayClient = undefined
+    clientRelayPool = undefined
     // The relay shared secret (T22a): minted fresh per apply, handed to the
     // gateway child through LAN_GATE_RELAY_SECRET and kept here for the
     // relay routes below. The push half never sees it.
@@ -765,10 +823,14 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
     // The shared-session table backing the relay's access control. The relay
     // route consumes it below; the activity tracker and idle sweeper (T22c)
     // keep its "quiet for idleHours → close" promise. The settings surface is
-    // a later task.
-    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
+    // a later task. (`home` is hoisted to apply() level — the CLI IPC
+    // delegate binds its socket under the same directory.)
+    // MS-1: the table now lives INSIDE the three-in-one state file (alongside
+    // the server identity and the paired-servers list); share-store's loader
+    // migrates a legacy zen-remote-shares.json in and every write preserves
+    // the other two top-level fields.
     const store = createShareStore({
-      file: join(home, 'zen-remote-shares.json'),
+      file: join(home, 'zen-remote-state.json'),
       idleHours: effective.values.idleHours,
     })
     // The live relay handler, kept so the admin shares route can read viewer
@@ -793,6 +855,16 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
     // clocks and the relay can walk the same chain for reachability.
     const parentIndex = createParentIndex()
     const tracker = createActivityTracker(store, parentIndex.parentOf)
+    // Track sessions explicitly unshared by a user or client during this row's
+    // lifetime so the `turn/start` (turn 1) fallback for `reuseLive` blank
+    // sessions never overrides an intentional manual unshare before Turn 1.
+    const manuallyUnshared = new Set<string>()
+    store.subscribe((ev) => {
+      if (ev.type === 'shared') manuallyUnshared.delete(ev.sessionId)
+      else if (ev.type === 'unshared' && (ev.reason === 'manual' || ev.reason === 'client')) {
+        manuallyUnshared.add(ev.sessionId)
+      }
+    })
     try {
       ctx.on('session/event', (session, event) => {
         // Record the parent link BEFORE tracking, so a child's very first
@@ -800,22 +872,36 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
         parentIndex.observe(session)
         const sessionId: unknown = session?.id
         if (typeof sessionId !== 'string' || sessionId === '') return
+        // When `session/create` reuses a blank session that was ALREADY live
+        // in memory (`reuseLive`), DSH emits no `agent/created`. If that blank
+        // session was not shared (e.g. `autoShareNewSessions` was turned on
+        // after it was pre-created, or its idle window expired in memory) and
+        // was not manually unshared while blank, share it as Turn 1 starts so
+        // `tracker.onEvent` right below marks it busy too.
+        if (isFirstTurnStart(session, event) && !manuallyUnshared.has(sessionId) && !store.isShared(sessionId)) {
+          try {
+            onSessionCreated(session.header, {
+              store,
+              autoShare: resolveConfig(config, readFileConfig(), process.env).values.autoShareNewSessions,
+              parentOf: parentIndex.parentOf,
+            })
+          } catch (error) {
+            logWarn('dsh-zen-remote cannot share new session "%s": %s', sessionId, message(error))
+          }
+        }
         tracker.onEvent(sessionId, event.type)
       })
     } catch (error) {
       logWarn('dsh-zen-remote cannot listen on "session/event": %s', message(error))
     }
-    // Auto-share and fork-following (T33a), off `agent/created` — the only
-    // host event that fires EXACTLY ONCE per NEW session. Its `source` is
-    // 'startup' for fresh creation (top-level, fork and subagent all go
+    // Auto-share and fork-following (T33a), off `agent/created`. Its `source`
+    // is 'startup' for fresh creation (top-level, fork and subagent all go
     // through the same factory call) and 'resume' when a persisted session
-    // re-enters the live store, so filtering on 'startup' is what keeps a
-    // manually-closed session closed across reopens — `session/created`
-    // re-fires on resume and `api-session/added` also fires when an agent is
-    // disposed, so neither qualifies. The payload's agent id IS the session
-    // id (dsh-agent keys its registry by it; its typert wire type is
-    // `dsh-session/types#SessionId`), and by announce time the fresh header
-    // already carries the subagent/fork markers the share decision reads.
+    // re-enters the live store. DSH's "New Session" (`createInWorkspace` →
+    // `session/create`) reuses persisted blank sessions (zero turns ever
+    // started) via `agents.resume`, which arrives with `source === 'resume'`;
+    // `isBlankSession` lets those reclaimed placeholders auto-share while
+    // keeping established conversations closed across reopens.
     // autoShareNewSessions is a volatile row setting: resolved at EVENT time,
     // never snapshotted here.
     try {
@@ -834,7 +920,12 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           // whose share it inherits through its parent, and the forwarded
           // status frames the client needs to announce the row never left.
           parentIndex.observe(agent.session)
-          if (source !== 'startup') return
+          const turnBoundaryOf = (s: unknown): TurnBoundaryLike | undefined => {
+            const ag = reflectNow()?.get('agents') as { turnBoundaryOf?: (sess: unknown) => TurnBoundaryLike } | undefined
+            return typeof ag?.turnBoundaryOf === 'function' ? ag.turnBoundaryOf(s) : undefined
+          }
+          if (source !== 'startup' && !(source === 'resume' && isBlankSession(agent.session, turnBoundaryOf))) return
+          if (typeof agent.id === 'string') manuallyUnshared.delete(agent.id)
           onSessionCreated(agent.session.header, {
             store,
             autoShare: resolveConfig(config, readFileConfig(), process.env).values.autoShareNewSessions,
@@ -882,6 +973,245 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
     } catch (error) {
       logWarn('dsh-zen-remote cannot listen on "sessionPersistence": %s', message(error))
     }
+    // CLI-1: the managed-ingress machinery MOVED OUT of the wizard route's
+    // inject so the CLI IPC delegate shares ONE set of managers / handler
+    // options with the browser routes (same caddyManager, same
+    // cloudflaredManager, same verification session, same relay store). The
+    // subprocess service is read the lazy way — off the reflection layer,
+    // which answers undefined on compositions without it — so the wizard
+    // options simply degrade to their 501 placeholders there.
+    const getConfig = (): ReturnType<typeof resolveConfig> => resolveConfig(config, readFileConfig(), process.env)
+    const subprocessService = reflectNow()?.get('subprocess') as SubprocessServiceLike | undefined
+    const caddyManager = subprocessService === undefined ? undefined : createCaddyManager({ subprocess: subprocessService, dshHome: home })
+    const cloudflaredManager = subprocessService === undefined ? undefined : createCloudflaredManager({ subprocess: subprocessService, dshHome: home })
+    for (const child of [caddyManager, cloudflaredManager]) {
+      if (child !== undefined) cliManagedChildren.push(child)
+    }
+    // The verification session lives in THIS manager set's closure (GW-9):
+    // memory-only by design, and a row reload rebuilds it — the same
+    // "stale" verdict the config fingerprint produces, arriving via the
+    // process generation instead.
+    const currentMode = (): string => getConfig().values.ingressMode
+    const detectLanCandidates = (): { ip: string; kind: 'tailscale' | 'lan'; iface: string }[] => {
+      try {
+        const nets = networkInterfaces()
+        const tailscale: { ip: string; kind: 'tailscale' | 'lan'; iface: string }[] = []
+        const primaryLan: { ip: string; kind: 'tailscale' | 'lan'; iface: string }[] = []
+        const bridgeLan: { ip: string; kind: 'tailscale' | 'lan'; iface: string }[] = []
+        for (const [iface, entries] of Object.entries(nets)) {
+          if (!Array.isArray(entries)) continue
+          const isContainerBridge = /^(?:docker\d*|br-|veth|cni\d*|flannel|virbr\d*|cali)/i.test(iface)
+          for (const entry of entries) {
+            if (!entry || entry.internal || entry.family !== 'IPv4') continue
+            const addr = entry.address
+            if (/^100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(addr)) {
+              tailscale.push({ ip: addr, kind: 'tailscale', iface })
+            } else if (
+              /^192\.168\./.test(addr)
+              || /^10\./.test(addr)
+              || /^172\.(?:1[6-9]|2\d|3[01])\./.test(addr)
+            ) {
+              if (isContainerBridge) bridgeLan.push({ ip: addr, kind: 'lan', iface })
+              else primaryLan.push({ ip: addr, kind: 'lan', iface })
+            }
+          }
+        }
+        return [...tailscale, ...primaryLan, ...bridgeLan]
+      } catch {
+        return []
+      }
+    }
+    // One runtime probe per request: the gateway's own status (source-IP
+    // detection + the ACTUAL port for snippets/QR), plus our processes'
+    // liveness for the projection.
+    const buildRuntime = async () => {
+      const lanAddresses = detectLanCandidates()
+      const lanAddress = (lanAddresses.find((c) => c.kind === 'lan') ?? lanAddresses[0])?.ip
+      try {
+        const response = await fetch(`http://127.0.0.1:${effective.values.port}/lan-gate/status`, { signal: AbortSignal.timeout(3000) })
+        if (!response.ok) return { caddyRunning: caddyManager?.isRunning() === true, lanAddress, lanAddresses }
+        const body = (await response.json()) as { host?: unknown; port?: unknown; lastForwardedSource?: unknown }
+        return {
+          lastForwardedSource: detectForwardedSource(body),
+          // GW-fix-3/M2: the wizard's snippets and QR target the
+          // gateway's ACTUAL port (it may have retried past the
+          // configured one).
+          gatewayActualPort: typeof body?.port === 'number' ? body.port : undefined,
+          gatewayActualHost: typeof body?.host === 'string' ? body.host : undefined,
+          lanAddress,
+          lanAddresses,
+          caddyRunning: caddyManager?.isRunning() === true,
+          cloudflaredRunning: cloudflaredManager?.isRunning() === true,
+          tunnelTokenConfigured: cloudflaredManager !== undefined,
+          cfTokenConfigured: cfTokenConfigured(home),
+        }
+      } catch {
+        // No answer is no detection — the status projection renders
+        // its null shape and the UI offers nothing.
+        return {
+          lanAddress,
+          lanAddresses,
+          caddyRunning: caddyManager?.isRunning() === true,
+          cloudflaredRunning: cloudflaredManager?.isRunning() === true,
+          tunnelTokenConfigured: tunnelTokenConfigured(home),
+          cfTokenConfigured: cfTokenConfigured(home),
+        }
+      }
+    }
+    const verification = createVerificationManager({
+      gatewayBase: `http://127.0.0.1:${effective.values.port}`,
+      getValues: () => getConfig().values,
+      // runtimeReady now covers the managed paths: Caddy must actually be
+      // alive; cloudflared arrives with GW-13b; the external path has no
+      // process of ours to wait for.
+      runtimeReady: () => {
+        const mode = currentMode()
+        if (mode === 'caddy') return caddyManager?.isRunning() === true
+        if (mode === 'cloudflared') return cloudflaredManager?.isRunning() === true
+        return true
+      },
+    })
+    const wizardOptionsFor = (admit: (req: IncomingMessage) => AdminAdmission): WizardHandlerOptions => ({
+      admit,
+      getConfig,
+      tokenStore: {
+        writeCfToken: (token) => { writeCfTokenFile(home, token) },
+        deleteCfToken: () => {
+          // Stop the consumers first (the mode-switch rule): whichever
+          // process might hold the token in its environment dies before
+          // the file disappears.
+          caddyManager?.stop()
+          cloudflaredManager?.stop()
+          deleteCfTokenFile(home)
+        },
+        cfTokenConfigured: () => cfTokenConfigured(home),
+        writeTunnelToken: (token) => { writeTunnelTokenFile(home, token) },
+      },
+      ...(caddyManager === undefined ? {} : {
+        caddy: {
+          start: async (input: { domain: string; httpsPort: number; gatewayPort: number }) => {
+            // 模式切换：starting managed Caddy stops any running cloudflared tunnel first,
+            // and restarts Caddy if it was already running with an older config.
+            cloudflaredManager?.stop()
+            if (caddyManager.isRunning()) caddyManager.stop()
+            // The token rides the child env only — read from the store
+            // inside the wiring, never through a route payload.
+            const token = readCfTokenFile(home)
+            if (token === undefined) return { ok: false as const, error: 'missing-token' as const }
+            return caddyManager.start({ ...input, cfToken: token })
+          },
+          stop: () => caddyManager.stop(),
+          status: () => (caddyManager.isRunning() ? 'running' as const : caddyManager.hasStarted() ? 'stopped' as const : 'never-started' as const),
+        },
+      }),
+      ...(cloudflaredManager === undefined ? {} : {
+        tunnel: {
+          checkDomain: (domain: string) => runTunnelCheck(
+            { readToken: () => readCfTokenFile(home) },
+            domain,
+          ),
+          setup: (input: { domain: string; tunnelId?: string }) => setupTunnel(
+            {
+              dshHome: home,
+              readToken: () => readCfTokenFile(home),
+              gatewayPort: async () => {
+                // The ingress service target is the gateway's ACTUAL
+                // port — same fallback as the caddy start route: probe
+                // /lan-gate/status first, fall back to the configured
+                // port when it does not answer (GW-fix-4/M2).
+                try {
+                  const response = await fetch(`http://127.0.0.1:${getConfig().values.port}/lan-gate/status`, { signal: AbortSignal.timeout(3000) })
+                  if (response.ok) {
+                    const body = (await response.json()) as { port?: unknown }
+                    if (typeof body?.port === 'number') return body.port
+                  }
+                } catch { /* fall through to the configured port */ }
+                return getConfig().values.port
+              },
+              cloudflared: {
+                start: async (startInput: { tunnelToken: string }) => {
+                  if (cloudflaredManager.isRunning()) cloudflaredManager.stop()
+                  const started = await cloudflaredManager.start({ tunnelToken: startInput.tunnelToken })
+                  return started.ok ? ({ ok: true } as const) : ({ ok: false, error: started.error ?? 'spawn-failed' } as const)
+                },
+                // 模式切换：starting the tunnel stops the managed Caddy.
+                stopCaddy: () => caddyManager?.stop(),
+              },
+            },
+            input,
+          ),
+          stop: () => cloudflaredManager.stop(),
+          status: () => (cloudflaredManager.isRunning() ? 'running' as const : cloudflaredManager.hasStarted() ? 'stopped' as const : 'never-started' as const),
+        },
+      }),
+      verify: { start: (input) => verification.start(input), check: () => verification.check() },
+      getRuntime: () => buildRuntime(),
+      trustProxy: {
+        resolved: () => {
+          const snapshot = resolveConfig(config, readFileConfig(), process.env)
+          return { value: snapshot.values.trustedProxies, source: snapshot.sources.trustedProxies }
+        },
+        write: async (expected, list) => {
+          const file = join(home, 'lan-gate.config.json')
+          const current = readFileConfig()
+          // Concurrent-write guard (GW-fix-2/L2): the route resolved
+          // the list moments ago; if the file layer moved since (a
+          // parallel trust click, a hand edit), refuse instead of
+          // clobbering the other writer's entry. Both sides compare
+          // normalized so an illegal file value reads as "empty", the
+          // same thing resolveConfig saw.
+          const now = typeof current.trustedProxies === 'string' ? current.trustedProxies : ''
+          if (parseProxyList(now).join(',') !== parseProxyList(expected).join(',')) return false
+          const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
+          await writeFile(tmp, `${JSON.stringify({ ...current, trustedProxies: list }, null, 2)}\n`, { mode: 0o600 })
+          await rename(tmp, file)
+          return true
+        },
+      },
+    })
+    const adminOptionsFor = (admit: (req: IncomingMessage) => AdminAdmission): AdminHandlerOptions => ({
+      admit,
+      gatewayBase: `http://127.0.0.1:${effective.values.port}`,
+      getConfig,
+      // Shares routes (T33a): the table above is the truth they serve and
+      // mutate. typertGateway and agents are deliberately NOT declared in
+      // any inject — adding them would keep the WHOLE admin prefix off
+      // 0.1.7 / Electron compositions that lack them — so they are read PER
+      // REQUEST through the reflection layer's store lookup (runtime
+      // `ctx.get`, declared `ctx.reflect.get`), which answers undefined
+      // when the service is absent. Property access is not an option:
+      // cordis refuses reads of services the context did not declare
+      // (`cannot get property … without inject`), which would turn every
+      // shares request into a 500.
+      store,
+      typert: () => reflectNow()?.get('typertGateway') as RelayGateway | undefined,
+      getPeer: createOwnerPeerSource(() => reflectNow()?.get('connection')),
+      listAgents: () => (reflectNow()?.get('agents') as { list(): readonly AgentStatusLike[] } | undefined)?.list() ?? [],
+      // The "who is looking" badge (T33a2): read through whichever relay
+      // handler is live right now. sessionQuery likewise — the share
+      // action reads the durable session header through it to judge
+      // subagent sessions, degrading to the projection identity when the
+      // composition lacks the service.
+      viewerCount: (id: string) => relayHandler?.viewerCount(id) ?? 0,
+      sessionQuery: () => reflectNow()?.get('sessionQuery') as SessionQueryLike | undefined,
+      // The plugin bridge listing (PB-5): the SAME registry this apply
+      // built and the SAME live consent reader the relay's plugins table
+      // uses — one source of truth per question. PB-11: the listing
+      // marks the plugins an adapter stands in for (live — a plugin
+      // that registered its own declaration stops being marked).
+      pluginBridge: {
+        registry,
+        getConsent: () => getConfig().values.pluginBridgeConsent,
+        adaptedPlugins: () => new Set(adapters.filter((adapter) => adapterOwnsRegistryEntry(adapter, registry.get(adapter.plugin))).map((adapter) => adapter.plugin)),
+      },
+    })
+    // The CLI IPC delegate's OWN handler instances (CLI-1): same options,
+    // same managers, same verification session as the browser routes below
+    // — only the admit differs, because the request arrived over the 0600
+    // socket (same user, same machine) instead of DSH's cookie wall.
+    cliAdminHandler = createAdminHandler(adminOptionsFor(noopAdmit))
+    cliWizardHandler = createWizardHandler(wizardOptionsFor(noopAdmit))
+
     // Settings-surface admin routes (T14). The browser cannot call the
     // gateway's loopback-only admin API from DSH's origin, so the host
     // process re-exposes it same-origin and the handler calls the gateway AS
@@ -898,42 +1228,7 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       webCtx.effect(() => webCtx.webServer.register({
         kind: 'prefix',
         path: ADMIN_ROUTE_PREFIX,
-        handler: createAdminHandler({
-          admit: (req) => webCtx.connection.admit(req),
-          gatewayBase: `http://127.0.0.1:${effective.values.port}`,
-          getConfig: () => resolveConfig(config, readFileConfig(), process.env),
-          // Shares routes (T33a): the table above is the truth they serve and
-          // mutate. typertGateway and agents are deliberately NOT in this
-          // inject's declaration list — adding them would keep the WHOLE
-          // admin prefix off 0.1.7 / Electron compositions that lack them —
-          // so they are read PER REQUEST through the reflection layer's
-          // store lookup (runtime `ctx.get`, declared `ctx.reflect.get`),
-          // which answers undefined when the service is absent. Property
-          // access is not an option: cordis refuses reads of services the
-          // context did not declare (`cannot get property … without inject`),
-          // which would turn every shares request into a 500.
-          store,
-          typert: () => webCtx.reflect.get('typertGateway') as RelayGateway | undefined,
-          getPeer: createOwnerPeerSource(() => webCtx.connection),
-          listAgents: () => (webCtx.reflect.get('agents') as { list(): readonly AgentStatusLike[] } | undefined)?.list() ?? [],
-          // The "who is looking" badge (T33a2): read through whichever relay
-          // handler is live right now. sessionQuery likewise — the share
-          // action reads the durable session header through it to judge
-          // subagent sessions, degrading to the projection identity when the
-          // composition lacks the service.
-          viewerCount: (id) => relayHandler?.viewerCount(id) ?? 0,
-          sessionQuery: () => webCtx.reflect.get('sessionQuery') as SessionQueryLike | undefined,
-          // The plugin bridge listing (PB-5): the SAME registry this apply
-          // built and the SAME live consent reader the relay's plugins table
-          // uses — one source of truth per question. PB-11: the listing
-          // marks the plugins an adapter stands in for (live — a plugin
-          // that registered its own declaration stops being marked).
-          pluginBridge: {
-            registry,
-            getConsent: () => resolveConfig(config, readFileConfig(), process.env).values.pluginBridgeConsent,
-            adaptedPlugins: () => new Set(adapters.filter((adapter) => adapterOwnsRegistryEntry(adapter, registry.get(adapter.plugin))).map((adapter) => adapter.plugin)),
-          },
-        }),
+        handler: createAdminHandler(adminOptionsFor((req) => webCtx.connection.admit(req))),
       }), 'dsh-zen-remote: admin routes')
     })
     // Gateway-wizard routes (GW-4, extended by GW-5): a separate LONGEST-
@@ -949,207 +1244,25 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
     // reloads the row from (trustedProxies is a restart field), restarting
     // the gateway with the new trust list. When the resolved value comes
     // from env or the row the route refuses instead: a file-layer write
-    // would be shadowed there.
+    // would be shadowed there. (CLI-1: the managers and the handler options
+    // moved OUT of this inject to apply() level — see wizardOptionsFor —
+    // so the CLI IPC delegate drives the SAME manager set; this effect only
+    // registers the route and stops the children with the row.)
     ctx.inject(['webServer', 'connection'], (wizardCtx) => {
-      // GW-13a: the managed Caddy lives in THIS row's closure — a row
-      // reload rebuilds the manager (and the row's disposal, below, kills
-      // the child), which is the reconcile-by-process-generation rule. The
-      // subprocess service is a lazy reflection lookup: adding it to the
-      // inject list would keep the whole wizard off compositions that lack
-      // it, and there `reflect.get` answers undefined instead.
-      const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh')
-      const subprocessService = wizardCtx.reflect.get('subprocess') as SubprocessServiceLike | undefined
-      const caddyManager = subprocessService === undefined ? undefined : createCaddyManager({ subprocess: subprocessService, dshHome })
-      const cloudflaredManager = subprocessService === undefined ? undefined : createCloudflaredManager({ subprocess: subprocessService, dshHome })
-      // The verification session lives in THIS manager's closure (GW-9):
-      // memory-only by design, and a row reload rebuilds it — the same
-      // "stale" verdict the config fingerprint produces, arriving via the
-      // process generation instead.
-      const currentMode = (): string => resolveConfig(config, readFileConfig(), process.env).values.ingressMode
-      const detectLanAddress = (): string | undefined => {
-        try {
-          const nets = networkInterfaces()
-          let tailscaleIp: string | undefined
-          let lanIp: string | undefined
-          for (const entries of Object.values(nets)) {
-            if (!Array.isArray(entries)) continue
-            for (const entry of entries) {
-              if (!entry || entry.internal || entry.family !== 'IPv4') continue
-              const addr = entry.address
-              if (
-                /^192\.168\./.test(addr)
-                || /^10\./.test(addr)
-                || /^172\.(?:1[6-9]|2\d|3[01])\./.test(addr)
-              ) {
-                lanIp ??= addr
-              } else if (/^100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(addr)) {
-                tailscaleIp ??= addr
-              }
-            }
-          }
-          return lanIp ?? tailscaleIp
-        } catch {
-          return undefined
-        }
-      }
-      // One runtime probe per request: the gateway's own status (source-IP
-      // detection + the ACTUAL port for snippets/QR), plus our processes'
-      // liveness for the projection.
-      const buildRuntime = async () => {
-        const lanAddress = detectLanAddress()
-        try {
-          const response = await fetch(`http://127.0.0.1:${effective.values.port}/lan-gate/status`, { signal: AbortSignal.timeout(3000) })
-          if (!response.ok) return { caddyRunning: caddyManager?.isRunning() === true, lanAddress }
-          const body = (await response.json()) as { port?: unknown; lastForwardedSource?: unknown }
-          return {
-            lastForwardedSource: detectForwardedSource(body),
-            // GW-fix-3/M2: the wizard's snippets and QR target the
-            // gateway's ACTUAL port (it may have retried past the
-            // configured one).
-            gatewayActualPort: typeof body?.port === 'number' ? body.port : undefined,
-            lanAddress,
-            caddyRunning: caddyManager?.isRunning() === true,
-            cloudflaredRunning: cloudflaredManager?.isRunning() === true,
-            tunnelTokenConfigured: cloudflaredManager !== undefined,
-            cfTokenConfigured: cfTokenConfigured(dshHome),
-          }
-        } catch {
-          // No answer is no detection — the status projection renders
-          // its null shape and the UI offers nothing.
-          return {
-            lanAddress,
-            caddyRunning: caddyManager?.isRunning() === true,
-            cloudflaredRunning: cloudflaredManager?.isRunning() === true,
-            tunnelTokenConfigured: tunnelTokenConfigured(dshHome),
-            cfTokenConfigured: cfTokenConfigured(dshHome),
-          }
-        }
-      }
-      const verification = createVerificationManager({
-        gatewayBase: `http://127.0.0.1:${effective.values.port}`,
-        getValues: () => resolveConfig(config, readFileConfig(), process.env).values,
-        // runtimeReady now covers the managed paths: Caddy must actually be
-        // alive; cloudflared arrives with GW-13b; the external path has no
-        // process of ours to wait for.
-        runtimeReady: () => {
-          const mode = currentMode()
-          if (mode === 'caddy') return caddyManager?.isRunning() === true
-          if (mode === 'cloudflared') return cloudflaredManager?.isRunning() === true
-          return true
-        },
-      })
       wizardCtx.effect(() => {
         const unregister = wizardCtx.webServer.register({
-        kind: 'prefix',
-        path: WIZARD_ROUTE_PREFIX,
-        handler: createWizardHandler({
-          admit: (req) => wizardCtx.connection.admit(req),
-          getConfig: () => resolveConfig(config, readFileConfig(), process.env),
-          tokenStore: {
-            writeCfToken: (token) => { writeCfTokenFile(dshHome, token) },
-            deleteCfToken: () => {
-              // Stop the consumers first (the mode-switch rule): whichever
-              // process might hold the token in its environment dies before
-              // the file disappears.
-              caddyManager?.stop()
-              cloudflaredManager?.stop()
-              deleteCfTokenFile(dshHome)
-            },
-            cfTokenConfigured: () => cfTokenConfigured(dshHome),
-            writeTunnelToken: (token) => { writeTunnelTokenFile(dshHome, token) },
-          },
-          ...(caddyManager === undefined ? {} : {
-            caddy: {
-              start: async (input: { domain: string; httpsPort: number; gatewayPort: number }) => {
-                // 模式切换：starting managed Caddy stops any running cloudflared tunnel first,
-                // and restarts Caddy if it was already running with an older config.
-                cloudflaredManager?.stop()
-                if (caddyManager.isRunning()) caddyManager.stop()
-                // The token rides the child env only — read from the store
-                // inside the wiring, never through a route payload.
-                const token = readCfTokenFile(dshHome)
-                if (token === undefined) return { ok: false as const, error: 'missing-token' as const }
-                return caddyManager.start({ ...input, cfToken: token })
-              },
-              stop: () => caddyManager.stop(),
-              status: () => (caddyManager.isRunning() ? 'running' as const : caddyManager.hasStarted() ? 'stopped' as const : 'never-started' as const),
-            },
-          }),
-          ...(cloudflaredManager === undefined ? {} : {
-            tunnel: {
-              checkDomain: (domain: string) => runTunnelCheck(
-                { readToken: () => readCfTokenFile(dshHome) },
-                domain,
-              ),
-              setup: (input: { domain: string; tunnelId?: string }) => setupTunnel(
-                {
-                  dshHome,
-                  readToken: () => readCfTokenFile(dshHome),
-                  gatewayPort: async () => {
-                    // The ingress service target is the gateway's ACTUAL
-                    // port — same fallback as the caddy start route: probe
-                    // /lan-gate/status first, fall back to the configured
-                    // port when it does not answer (GW-fix-4/M2).
-                    try {
-                      const response = await fetch(`http://127.0.0.1:${resolveConfig(config, readFileConfig(), process.env).values.port}/lan-gate/status`, { signal: AbortSignal.timeout(3000) })
-                      if (response.ok) {
-                        const body = (await response.json()) as { port?: unknown }
-                        if (typeof body?.port === 'number') return body.port
-                      }
-                    } catch { /* fall through to the configured port */ }
-                    return resolveConfig(config, readFileConfig(), process.env).values.port
-                  },
-                  cloudflared: {
-                    start: async (startInput: { tunnelToken: string }) => {
-                      if (cloudflaredManager.isRunning()) cloudflaredManager.stop()
-                      const started = await cloudflaredManager.start({ tunnelToken: startInput.tunnelToken })
-                      return started.ok ? ({ ok: true } as const) : ({ ok: false, error: started.error ?? 'spawn-failed' } as const)
-                    },
-                    // 模式切换：starting the tunnel stops the managed Caddy.
-                    stopCaddy: () => caddyManager?.stop(),
-                  },
-                },
-                input,
-              ),
-              stop: () => cloudflaredManager.stop(),
-              status: () => (cloudflaredManager.isRunning() ? 'running' as const : cloudflaredManager.hasStarted() ? 'stopped' as const : 'never-started' as const),
-            },
-          }),
-          verify: { start: (input) => verification.start(input), check: () => verification.check() },
-          getRuntime: () => buildRuntime(),
-          trustProxy: {
-            resolved: () => {
-              const snapshot = resolveConfig(config, readFileConfig(), process.env)
-              return { value: snapshot.values.trustedProxies, source: snapshot.sources.trustedProxies }
-            },
-            write: async (expected, list) => {
-              const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
-              const file = join(home, 'lan-gate.config.json')
-              const current = readFileConfig()
-              // Concurrent-write guard (GW-fix-2/L2): the route resolved
-              // the list moments ago; if the file layer moved since (a
-              // parallel trust click, a hand edit), refuse instead of
-              // clobbering the other writer's entry. Both sides compare
-              // normalized so an illegal file value reads as "empty", the
-              // same thing resolveConfig saw.
-              const now = typeof current.trustedProxies === 'string' ? current.trustedProxies : ''
-              if (parseProxyList(now).join(',') !== parseProxyList(expected).join(',')) return false
-              const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
-              await writeFile(tmp, `${JSON.stringify({ ...current, trustedProxies: list }, null, 2)}\n`, { mode: 0o600 })
-              await rename(tmp, file)
-              return true
-            },
-          },
-        }),
-      })
-      // H1: the row's disposal must not orphan the managed children — the
-      // Caddy/cloudflared processes die WITH the row that spawned them,
-      // before the route registration unregisters.
-      return () => {
-        caddyManager?.stop()
-        cloudflaredManager?.stop()
-        unregister()
-      }
+          kind: 'prefix',
+          path: WIZARD_ROUTE_PREFIX,
+          handler: createWizardHandler(wizardOptionsFor((req) => wizardCtx.connection.admit(req))),
+        })
+        // H1: the row's disposal must not orphan the managed children — the
+        // Caddy/cloudflared processes die WITH the row that spawned them,
+        // before the route registration unregisters.
+        return () => {
+          caddyManager?.stop()
+          cloudflaredManager?.stop()
+          unregister()
+        }
       }, 'dsh-zen-remote: wizard routes')
     })
     // The idle sweeper (T22c): every minute, hand the table the CURRENT
@@ -1355,101 +1468,126 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           getGatewaySummary: gatewaySummary,
           getProfileName: profileName,
           getPluginVersion: () => pluginVersion,
+          lang: resolveActiveLang,
         }),
       }), 'dsh-zen-remote: client routes (host)')
     })
-  } else {
-    // Sub-client half (T16, T23a): pairing claim + connection status, talking to
-    // the SERVER's gateway instead of running one. Same admission wall as
-    // the admin routes — and, like them, a composition without a connection
-    // service (Electron carries none) simply never mounts the routes. The
-    // handler keeps the RAW row object: serverUrl / deviceToken are volatile
-    // ({ get() } wrapped), so every request reads them live through
-    // unwrapVolatile — an apply-time snapshot would go stale the moment the
-    // settings page pairs or unpairs.
-    //
-    // The relay client (T23a) reads the SAME volatile fields live at every
-    // request; the address passes the claim route's normalizer, and an
-    // address that no longer normalizes counts as missing — a hand-edited
-    // row must not receive the pairing token.
+    // CLI-1: the IPC delegate's client face on a serving role — remote-status
+    // and the debug report answer (both are every role's own); the IPC
+    // prefix gate covers the pairing routes (409 wrong-role before any
+    // request reaches here), and the handler keeps the host mount's
+    // least-exposure wall besides.
+    cliClientHandler = createClientHandler({
+      admit: noopAdmit,
+      getRowConfig: () => config,
+      remoteStatusOnly: true,
+      getServiceProbe: uploadServiceProbe(ctx),
+      getLogSnapshot: () => ring.snapshot(),
+      getGatewaySummary: gatewaySummary,
+      getProfileName: profileName,
+      getPluginVersion: () => pluginVersion,
+      lang: resolveActiveLang,
+    })
+  }
+  if (connectsRole(effective.values.role)) {
+    // Sub-client half (T16, T23a; MS-5 pool rewiring): the paired-servers
+    // connection pool instead of the single row-driven client. The row's
+    // serverUrl/deviceToken survive only as the LEGACY source — read once
+    // here so an old single-server row migrates into
+    // `zen-remote-state.json`'s paired list (state-store's migration keeps
+    // the list's other entries); from then on the pool's paired list is the
+    // single truth, edited by the client routes' claim/unpair.
     const row = config as Record<string, unknown>
-    const relayClient = createRelayClient({
-      getServerUrl: () => normalizedRowServerUrl(row),
-      getToken: () => {
-        const value = unwrapVolatile(row.deviceToken)
-        return typeof value === 'string' && value !== '' ? value : undefined
-      },
+    // (`home` is hoisted to apply() level — the pool's state file and the
+    // CLI IPC socket share the same directory.)
+    // MS-3/MS-5: the intercept handle is created inside the typertGateway
+    // inject below, but the POOL's state callbacks (created first) forward
+    // to it — the closure is fine (the callbacks fire after apply() returned
+    // or not at all); the declaration just moved up so the wiring reads
+    // top-down.
+    let interceptHandle: InterceptHandle | undefined
+    const legacyCredentials = (): { serverUrl?: string; deviceToken?: string } | undefined => {
+      const url = unwrapVolatile(row.serverUrl)
+      const token = unwrapVolatile(row.deviceToken)
+      const serverUrl = typeof url === 'string' && url.trim() !== '' ? url : undefined
+      const deviceToken = typeof token === 'string' && token !== '' ? token : undefined
+      return serverUrl === undefined && deviceToken === undefined ? undefined : { serverUrl, deviceToken }
+    }
+    // CU-1 lifecycle: the pool's per-server link flips enter the ring —
+    // `online` with the entry and its handshake server id, `offline` with
+    // the failure code (lastError is a short code by contract, never free
+    // text). The client's subscribe re-announces the CURRENT state when only
+    // the handshake identity moved (the T59 heartbeat), so the per-entry
+    // dedupe keeps the heartbeats out of the ring: one line per actual state
+    // change. Every event ALSO reaches the intercept's pool hub — the merged
+    // streams re-scan `pool.entries()` on it.
+    const poolRingStates = new Map<string, string>()
+    const relayPool = createRelayPool({
+      stateFile: join(home, 'zen-remote-state.json'),
+      legacySource: legacyCredentials,
       // Interface compatibility (T42): after each completed handshake this
       // side computes its OWN fingerprints against THIS process's typert
       // registry (read per call — at creation time the row context may still
-      // be assembling), and the relay client stores the group-by-group
-      // verdict the status route reports.
+      // be assembling), and the client stores the group-by-group verdict the
+      // status route reports.
       computeOwnFingerprints: () => computeFingerprints(ctx),
+      onStateChange: ({ entryId, serverId, state, lastError }) => {
+        if (poolRingStates.get(entryId) !== state) {
+          poolRingStates.set(entryId, state)
+          if (state === 'online') ring.push('info', 'relay pool online (entry=%s server=%s)', entryId, serverId ?? '?')
+          else if (state === 'offline') ring.push('warn', 'relay pool offline (entry=%s code=%s)', entryId, lastError ?? '?')
+        }
+        interceptHandle?.notePoolEvent()
+      },
+      onServerRemoved: ({ entryId, reason }) => {
+        poolRingStates.delete(entryId)
+        ring.push('info', 'relay pool server removed (entry=%s reason=%s)', entryId, reason)
+        interceptHandle?.notePoolEvent()
+      },
     })
-    clientRelayClient = relayClient
-    // The plugin bridge's live verdict (PB-2), the CLIENT role's job — a host
-    // has no remote sessions of its own to bridge anything into. Computed PER
+    clientRelayPool = relayPool
+    // A stopped or reloaded row must not leave a stale pool where the module
+    // getter can hand it out (T23a-fix's discipline), and its clients'
+    // reconnect machinery must not outlive the row either: stop() ends every
+    // client (which cancels armed retry timers and blocks scheduling). The
+    // identity guard keeps a slow dispose from clearing a NEWER row's pool.
+    ctx.effect(() => () => {
+      relayPool.stop()
+      if (clientRelayPool === relayPool) clientRelayPool = undefined
+    }, 'dsh-zen-remote: relay pool disposal')
+    // The plugin bridge's live verdict (PB-2), per POOL ENTRY now (MS-5) — a
+    // host has no remote sessions of its own to bridge anything into, and
+    // server A's verdicts must never answer for server B's. Computed PER
     // CALL (never a stored conclusion): the local registry is this apply's
-    // own closure, the server's table is the LAST handshake's `plugins`
+    // own closure, the entry's table is ITS LAST handshake's `plugins`
     // (undefined until one succeeded — an old server reads server-too-old),
-    // and `online` is the client's CURRENT state — so a registry change, a
+    // and `online` is that client's CURRENT state — so a registry change, a
     // fresh handshake or a link flip shows up at the very next read.
-    const pluginBridgeStatus = (): BridgeStatus[] =>
-      compareBridges(registry.list(), relayClient.handshakeInfo?.plugins, relayClient.state === 'online')
-    // CU-1 lifecycle: the relay link's flips enter the ring — `online` with
-    // the server id it handshook, `offline` with the mapped failure code
-    // (relayClient.lastError is a short code by contract, never free text).
-    // subscribe re-announces the CURRENT state when only the handshake
-    // identity moved (the T59 heartbeat), so the dedupe below keeps the
-    // heartbeats out of the ring: one line per actual state change.
-    let lastRelayRingState: string | undefined
-    const offRelayRing = relayClient.subscribe((state) => {
-      if (state === lastRelayRingState) return
-      lastRelayRingState = state
-      if (state === 'online') {
-        ring.push('info', 'relay link online (server=%s)', relayClient.handshakeInfo?.serverId ?? '?')
-      } else if (state === 'offline') {
-        ring.push('warn', 'relay link offline (code=%s)', relayClient.lastError ?? '?')
-      }
-    })
-    // A stopped or reloaded row must not leave a stale instance where the
-    // module getter can hand it out (T23a-fix), and its reconnect machinery
-    // (T43) must not outlive the row either: stop() cancels the armed retry
-    // timer and blocks further scheduling. The identity guard keeps a slow
-    // dispose from clearing a NEWER row's instance that a reload already
-    // installed.
-    ctx.effect(() => () => {
-      offRelayRing()
-      relayClient.stop()
-      if (clientRelayClient === relayClient) clientRelayClient = undefined
-    }, 'dsh-zen-remote: relay client disposal')
-    // Credentials watch (T43): serverUrl / deviceToken are volatile row
-    // fields, and a pairing write (or unpair) commits them WITHOUT a row
-    // restart. The loader announces the commit on the row context; the
-    // client drops its pending reconnect wait and dials the new credentials
-    // immediately. Failure to subscribe degrades to a warning — the ladder
-    // and the per-request getters keep working without it.
-    // T59 rides the same announcement, and ONLY that announcement (T59-fix):
-    // the row's `serverName` is this device's name, and a USER-committed
-    // change is forwarded to the gateway's device table — but the event
-    // fires for EVERY volatile commit (an unrelated knob, or the settings
-    // page's own server-driven follow write arriving at startup), so the
-    // listener filters on the changed paths. A push fires only when
-    // `serverName` itself moved and differs from the server's record
-    // (queueDeviceName's contract) — which is what keeps the follow write
-    // from bouncing back and forth. NOT pushed at startup either: the row's
-    // loaded name is stale by definition (the server's table may have been
-    // edited while we were gone) and an unconditional boot-time push would
-    // overwrite an administrator's rename. A rename committed offline and
-    // lost to a process exit therefore stays local until the user edits it
-    // again — accepted; the server's record wins by default.
+    const pluginBridgeStatusFor = (serverId: string | undefined, client: RelayClient): BridgeStatus[] =>
+      compareBridges(registry.list(), client.handshakeInfo?.plugins, client.state === 'online')
+    // Device-name watch (T59 through MS-5's pool): the row's `serverName` is
+    // this device's name, and a USER-committed change is broadcast to EVERY
+    // paired server's gateway device table — one-way (MS decision: the
+    // server's record never rewrites the row). The loader announces the
+    // commit on the row context, but the event fires for EVERY volatile
+    // commit (an unrelated knob, or a settings page's own server-driven
+    // follow write), so the listener filters on the changed paths. Each
+    // client pushes only when the name differs from its server's record
+    // (queueDeviceName's contract) — which is what keeps a follow write from
+    // bouncing back and forth. NOT pushed at startup either: the row's
+    // loaded name is stale by definition and an unconditional boot-time push
+    // would overwrite an administrator's rename. A rename committed offline
+    // and lost to a process exit stays local until the user edits it again —
+    // accepted; the server's record wins by default. (The old T43
+    // credentialsChanged half of this listener is gone with the row client:
+    // the pool's credentials live in the state file, edited by claim/unpair,
+    // and its clients react to THOSE on their own.)
     ctx.effect(() => {
       try {
         const off = ctx.on('loader/volatile-update', (paths) => {
-          relayClient.credentialsChanged()
           if (!volatileUpdateTouchesServerName(paths)) return
           const name = unwrapVolatile(row.serverName)
-          if (typeof name === 'string' && name.trim() !== '') relayClient.queueDeviceName(name)
+          if (typeof name === 'string' && name.trim() !== '') relayPool.queueDeviceNameAll(name)
         })
         return () => {
           off()
@@ -1459,23 +1597,15 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
         return () => {}
       }
     }, 'dsh-zen-remote: relay credentials watcher')
-    // One connection attempt at startup (T23a). Failures only log — the
-    // status route surfaces the resulting state, and the client's own
-    // backoff ladder (T43) takes over from the first failure. An unpaired
-    // row is the normal not-configured shape and stays silent.
-    void relayClient.connect().catch((error) => {
-      if (error instanceof RelayError && error.code === 'unpaired') return
-      const code = error instanceof RelayError ? error.code : 'error'
-      logWarn('dsh-zen-remote relay client initial connect failed (%s): %s', code, message(error))
-    })
     // The typertGateway interception (T23b-1): remote-session calls ride the
     // relay, everything else reaches the local gateway untouched. The live
     // diagnostics flow to the client status route through whichever of the
     // two slots is filled — an installed handle, or the shape verdict that
     // REFUSED an install (both belong on the settings surface). A
     // composition without typertGateway (0.1.7 client) leaves both empty and
-    // the status answer simply carries no intercept field.
-    let interceptHandle: InterceptHandle | undefined
+    // the status answer simply carries no intercept field. (The handle's
+    // declaration itself sits above, beside the pool — its callbacks forward
+    // pool events here.)
     let interceptRefused: GatewayShapeCheck | undefined
     // T62: the browser's current-session report, held here and read live by
     // the intercept (which cannot reach the browser's localStorage — it
@@ -1483,8 +1613,9 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
     // first report arrives the value is `unavailable` and the intercept
     // keeps its conservative tombstone behavior.
     let reportedCurrentSession: CurrentSessionRead = { kind: 'unavailable' }
-    const onCurrentSession = (read: CurrentSessionRead): void => {
+    const onCurrentSession = (read: CurrentSessionRead, reportedLang?: 'zh' | 'en'): void => {
       reportedCurrentSession = read
+      if (reportedLang !== undefined) reportedBrowserLang = reportedLang
       // Re-judge NOW — the merger dedupes no-change calls, so a report that
       // carries nothing new costs one compare.
       interceptHandle?.currentSessionChanged()
@@ -1502,18 +1633,21 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
     // between two stream refreshes waits for the next refresh by design
     // (the documented ceiling in merge-streams.ts). Read-only consumption:
     // nothing below ever mutates what a merger handed over.
-    const knownSessionShares = new Map<SessionInventorySlot, ReadonlySet<string>>()
+    // MS-5: each share is tagged with the serverId its stream asked the slot
+    // for, so the plugin-route's per-server face can answer the union of ONE
+    // server's ids — a rewrite against server A must never see B's ids.
+    const knownSessionShares = new Map<SessionInventorySlot, { serverId: string | undefined; ids: ReadonlySet<string> }>()
     const knownRealIds = new Set<string>()
     const rebuildKnownRealIds = (): void => {
       knownRealIds.clear()
       for (const share of knownSessionShares.values()) {
-        for (const id of share) knownRealIds.add(id)
+        for (const id of share.ids) knownRealIds.add(id)
       }
     }
-    const createSessionInventorySlot = (): SessionInventorySlot => {
+    const createSessionInventorySlot = (serverId?: string): SessionInventorySlot => {
       const slot: SessionInventorySlot = {
         replace(ids) {
-          knownSessionShares.set(slot, ids)
+          knownSessionShares.set(slot, { serverId, ids })
           rebuildKnownRealIds()
         },
         dispose() {
@@ -1522,6 +1656,17 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       }
       return slot
     }
+    /** MS-5: one server's share of the union, for the plugin-route rewrite's
+     * per-server face. An entry that never reported (its stream not open
+     * yet) contributes nothing — the request-local scan still runs. */
+    const knownRealIdsForServer = (serverId: string): ReadonlySet<string> => {
+      const out = new Set<string>()
+      for (const share of knownSessionShares.values()) {
+        if (share.serverId !== serverId) continue
+        for (const id of share.ids) out.add(id)
+      }
+      return out
+    }
     const interceptDiagnostics = (): InterceptDiagnostics | undefined => {
       if (interceptHandle !== undefined) return interceptHandle.diagnostics()
       if (interceptRefused !== undefined) {
@@ -1549,9 +1694,14 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       }
       const handle = installIntercept({
         raw,
-        relay: relayClient,
-        getServerId: () => relayClient.handshakeInfo?.serverId,
+        // MS-5 POOL mode: routing and merging read the relay pool — every
+        // call/stream/event rides the virtual id's serverId half to ITS
+        // server, the three global reads merge ALL paired servers in pairing
+        // order. (The single-server `relay` + `getServerId` form is gone
+        // from the wiring with the row client.)
+        pool: relayPool,
         getCurrentSession: () => reportedCurrentSession,
+        lang: resolveActiveLang,
         // PB-25b: each merged stream reports its real-session inventory
         // share into the union above.
         createSessionInventorySlot,
@@ -1643,8 +1793,9 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       }
       // Shape first, like the typert wrap: a failed check leaves every route
       // exactly as it was — local uploads untouched, remote uploads keep
-      // failing with the honest local error.
-      const shape = checkFetchRouteShape(raw)
+      // failing with the honest local error. (The media note rides along:
+      // this wiring always hands a resolveRemoteFileScope over, P55-2.)
+      const shape = checkFetchRouteShape(raw, true)
       if (!shape.ok) {
         fetchRouteRefused = shape
         logWarn('dsh-zen-remote fetch-route intercept not installed: %s', shape.reasons.join('; '))
@@ -1652,8 +1803,14 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       }
       const handle = installFetchRouteIntercept({
         connection: raw,
-        relay: relayClient,
-        getServerId: () => relayClient.handshakeInfo?.serverId,
+        // MS-5 pool mode: each upload's serverId half picks its own client.
+        getRelayForServer: (serverId) => relayPool.getByServerId(serverId)?.client,
+        // P55-2: the /api/file media route forwards to the session the
+        // intercept currently holds — read LIVE per request, so an uninstalled
+        // (or not-yet-installed) typert wrap answers undefined and the media
+        // request passes through to the local route.
+        resolveRemoteFileScope: (filePath) => interceptHandle?.resolveRemoteFileScope(filePath),
+        lang: resolveActiveLang,
         log: (format, ...args) => { logInfo(`dsh-zen-remote ${format}`, ...args) },
       })
       fetchRouteHandle = handle
@@ -1719,7 +1876,9 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       }
       // Shape against the proxy first (fetchRoutes reads through it); the
       // raw instance comes off the same symbols slot the inject path uses.
-      const shape = checkFetchRouteShape(connection)
+      // (The media note rides along — same install options as the inject
+      // path, P55-2.)
+      const shape = checkFetchRouteShape(connection, true)
       if (!shape.ok) {
         // Structural mismatch is a verdict, not a wait: record the attempt
         // and stop. A later inject trigger may still install (it checks the
@@ -1740,8 +1899,12 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       }
       const handle = installFetchRouteIntercept({
         connection: raw,
-        relay: relayClient,
-        getServerId: () => relayClient.handshakeInfo?.serverId,
+        // MS-5 pool mode: each upload's serverId half picks its own client.
+        getRelayForServer: (serverId) => relayPool.getByServerId(serverId)?.client,
+        // P55-2: same live read as the inject path — the media route follows
+        // whichever typert intercept is currently installed.
+        resolveRemoteFileScope: (filePath) => interceptHandle?.resolveRemoteFileScope(filePath),
+        lang: resolveActiveLang,
         log: (format, ...args) => { logInfo(`dsh-zen-remote ${format}`, ...args) },
       })
       fetchRouteHandle = handle
@@ -1810,9 +1973,16 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       const handle = installPluginRouteIntercept({
         webServer: raw,
         registry,
-        relay: relayClient,
-        getServerId: () => relayClient.handshakeInfo?.serverId,
-        getStatus: pluginBridgeStatus,
+        // MS-5 pool mode: validation, forwarding and response rewriting are
+        // judged against the located id's OWN server — its relay client, its
+        // bridge verdicts (its handshake's plugin table against the local
+        // registry) and its own known-real-id inventory.
+        getRelayForServer: (serverId) => relayPool.getByServerId(serverId)?.client,
+        getStatusForServer: (serverId) => {
+          const entry = relayPool.getByServerId(serverId)
+          return entry !== undefined ? pluginBridgeStatusFor(entry.serverId, entry.client) : []
+        },
+        getKnownRealIdsForServer: knownRealIdsForServer,
         adapters,
         // PB-12: the browser's currently open session — a VIRTUAL id means
         // a remote panel is the request's origin, the signal the adapter
@@ -1836,24 +2006,36 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
         if (pluginRouteHandle === handle) pluginRouteHandle = undefined
       }, 'dsh-zen-remote: plugin route intercept')
     })
+    // CLI-1: one options factory, two handler instances — the browser mount
+    // below keeps its admit wall, and the CLI IPC delegate's instance (same
+    // pool, same diagnostics getters, same everything but admit) lets the
+    // local CLI drive THIS pool directly over the 0600 socket.
+    const clientOptionsFor = (admit: (req: IncomingMessage) => AdminAdmission, probeCtx: Context) => ({
+      admit,
+      getRowConfig: () => config,
+      // MS-5 POOL mode: the paired list is the truth — claim pairs into
+      // the pool (the token never reaches the browser), unpair/reconnect
+      // address pool entries, and status / remote-status report every
+      // server. The row still rides along for the non-connection knobs
+      // (the debug report's config summary) — never for credentials.
+      pool: relayPool,
+      getPluginBridgeStatusForServer: pluginBridgeStatusFor,
+      getIntercept: interceptDiagnostics,
+      getFetchRouteIntercept: fetchRouteDiagnostics,
+      getServiceProbe: uploadServiceProbe(probeCtx),
+      getPluginRouteIntercept: pluginRouteDiagnostics,
+      onCurrentSession,
+      getLogSnapshot: () => ring.snapshot(),
+      getProfileName: profileName,
+      getPluginVersion: () => pluginVersion,
+      lang: resolveActiveLang,
+    })
+    cliClientHandler = createClientHandler(clientOptionsFor(noopAdmit, ctx))
     ctx.inject(['webServer', 'connection'], (clientCtx) => {
       clientCtx.effect(() => clientCtx.webServer.register({
         kind: 'prefix',
         path: CLIENT_ROUTE_PREFIX,
-        handler: createClientHandler({
-          admit: (req) => clientCtx.connection.admit(req),
-          getRowConfig: () => config,
-          getRelayClient: () => relayClient,
-          getIntercept: interceptDiagnostics,
-          getFetchRouteIntercept: fetchRouteDiagnostics,
-          getServiceProbe: uploadServiceProbe(clientCtx),
-          getPluginRouteIntercept: pluginRouteDiagnostics,
-          getPluginBridgeStatus: pluginBridgeStatus,
-          onCurrentSession,
-          getLogSnapshot: () => ring.snapshot(),
-          getProfileName: profileName,
-          getPluginVersion: () => pluginVersion,
-        }),
+        handler: createClientHandler(clientOptionsFor((req) => clientCtx.connection.admit(req), clientCtx)),
       }), 'dsh-zen-remote: client routes')
     })
   }
@@ -1904,11 +2086,57 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
     // Registration failure degrades to a warning, like the session feeds
     // above: the poll trigger keeps the watcher fully functional without it.
     try {
-      ctx.on('loader/volatile-update', () => { watcher.checkNow() })
+      ctx.on('loader/volatile-update', (paths) => {
+        if (Array.isArray(paths)) {
+          const topKeys = paths
+            .map((p) => (Array.isArray(p) && typeof p[0] === 'string' ? p[0] : undefined))
+            .filter((k): k is string => k !== undefined)
+          if (topKeys.length > 0) clearUnshadowedRowKeys(home, topKeys)
+        }
+        watcher.checkNow()
+      })
     } catch (error) {
       logWarn('dsh-zen-remote: cannot listen on "loader/volatile-update": %s', message(error))
     }
-    return watcher.stop
+    // CLI-1: hot-swap THIS row generation's delegate into the module-level
+    // IPC server (acquire is synchronous — apply() runs inside cordis; the
+    // first bind completes in the background and the CLI client retries
+    // until then). writeCliConfig's onAfterWrite re-checks the fingerprint
+    // IMMEDIATELY, so a CLI config write to a restart-required field
+    // reloads the row without waiting out the 2s poll. Every role getter
+    // re-resolves per call: ping answers the CURRENT effective role even in
+    // the instant before a pending reload lands. The IPC lifecycle rides
+    // this existing effect on purpose — role-wiring pins the top-level
+    // effect counts, so it may not register its own.
+    const delegate: CliIpcDelegate = {
+      role: () => resolveConfig(config, readFileConfig(), process.env).values.role,
+      serverName: () => resolveConfig(config, readFileConfig(), process.env).values.serverName,
+      profileName,
+      pluginVersion: () => pluginVersion,
+      writeConfig: (input) => writeCliConfig({
+        dshHome: home,
+        row: config as Record<string, unknown>,
+        env: process.env,
+        set: input.set,
+        unset: input.unset,
+        onAfterWrite: () => { watcher.checkNow() },
+      }),
+      wizardHandler: cliWizardHandler,
+      adminHandler: cliAdminHandler,
+      clientHandler: cliClientHandler,
+    }
+    const cliIpc = acquireCliIpcServer(home, delegate)
+    return () => {
+      // Release THIS row's hold (a concurrent reload's new acquire keeps
+      // the socket alive — that is the coordinator's grace window). The
+      // managed ingress children die with the row here too: on compositions
+      // WITHOUT a webServer the wizard effect above never fires, so this is
+      // the only stop they would ever get (with webServer both stop — stop
+      // is idempotent, safe before any start).
+      cliIpc.release()
+      watcher.stop()
+      for (const child of cliManagedChildren) child.stop()
+    }
   }, 'dsh-zen-remote: restart watcher')
   // The upload route carries the T17 admission wall too: webServer routes
   // skip DSH's /api authentication, so without the connection service's