dsh-zen-remote 2.3.11 → 2.4.0

package/lib/index.js

@@ -20,17 +20,17 @@ import { lstat, mkdir, open, realpath, rename, rm, writeFile } from 'node:fs/pro
 import { randomBytes } from 'node:crypto';
 import { homedir, networkInterfaces } from 'node:os';
 import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { readFileConfig, resolveConfig, unwrapVolatile } from './config.js';
+import { readFileConfig, resolveConfig, unwrapVolatile, servesRole, connectsRole } from './config.js';
 import { createActivityTracker, createParentIndex, seedParentIndexFromSnapshots, startSweeper } from './activity.js';
 import { ADMIN_ROUTE_PREFIX, createAdminHandler } from './admin-routes.js';
-import { normalizedRowServerUrl } from './client-pairing.js';
 import { CLIENT_ROUTE_PREFIX, createClientHandler } from './client-routes.js';
 import { responseJson, sameOriginPost } from './http.js';
 import { onSessionCreated, restoreBusy } from './share-ops.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 { volatileUpdateTouchesServerName } from './relay-client.js';
 import { computeFingerprints } from './fingerprint.js';
 import { runSelfCheck, installIntercept } from './intercept.js';
 import { checkGatewayShape } from './intercept-shape.js';
@@ -58,12 +58,14 @@ 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';
 // The loader's config schema (settings form) and the role normalizer live in
 // src/config.ts next to the resolution they describe; re-exported so the
 // 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
 // the package root, and `..` resolves there both from this file (via the
@@ -124,10 +126,27 @@ const MAX_COLLISION_TRIES = 100;
  * compositions that never ran this module's apply).
  */
 let clientRelayClient;
-/** 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() {
     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;
+/** The live client-role relay pool, if one was built. */
+export function getRelayPool() {
+    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
@@ -447,6 +466,8 @@ export async function handleUpload(ctx, maxBytes, req, res, admit, warn) {
  *   request.
  */
 export function apply(ctx, config = {}) {
+    const initialHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    applyUnshadowedRowKeys(initialHome, config);
     // 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:
@@ -635,10 +656,44 @@ export function apply(ctx, config = {}) {
             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 = () => ({ peer: {} });
+    const reflectNow = () => ctx.reflect;
+    let cliWizardHandler;
+    let cliAdminHandler;
+    let cliClientHandler;
+    let reportedBrowserLang;
+    const resolveActiveLang = () => {
+        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 = [];
+    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.
@@ -668,10 +723,14 @@ export function apply(ctx, config = {}) {
         // 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
@@ -790,6 +849,253 @@ export function apply(ctx, config = {}) {
         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 = () => resolveConfig(config, readFileConfig(), process.env);
+        const subprocessService = reflectNow()?.get('subprocess');
+        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 = () => getConfig().values.ingressMode;
+        const detectLanCandidates = () => {
+            try {
+                const nets = networkInterfaces();
+                const tailscale = [];
+                const primaryLan = [];
+                const bridgeLan = [];
+                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());
+                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) => ({
+            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) => {
+                        // 模式切换：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, error: 'missing-token' };
+                        return caddyManager.start({ ...input, cfToken: token });
+                    },
+                    stop: () => caddyManager.stop(),
+                    status: () => (caddyManager.isRunning() ? 'running' : caddyManager.hasStarted() ? 'stopped' : 'never-started'),
+                },
+            }),
+            ...(cloudflaredManager === undefined ? {} : {
+                tunnel: {
+                    checkDomain: (domain) => runTunnelCheck({ readToken: () => readCfTokenFile(home) }, domain),
+                    setup: (input) => 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());
+                                    if (typeof body?.port === 'number')
+                                        return body.port;
+                                }
+                            }
+                            catch { /* fall through to the configured port */ }
+                            return getConfig().values.port;
+                        },
+                        cloudflared: {
+                            start: async (startInput) => {
+                                if (cloudflaredManager.isRunning())
+                                    cloudflaredManager.stop();
+                                const started = await cloudflaredManager.start({ tunnelToken: startInput.tunnelToken });
+                                return started.ok ? { ok: true } : { ok: false, error: started.error ?? 'spawn-failed' };
+                            },
+                            // 模式切换：starting the tunnel stops the managed Caddy.
+                            stopCaddy: () => caddyManager?.stop(),
+                        },
+                    }, input),
+                    stop: () => cloudflaredManager.stop(),
+                    status: () => (cloudflaredManager.isRunning() ? 'running' : cloudflaredManager.hasStarted() ? 'stopped' : 'never-started'),
+                },
+            }),
+            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) => ({
+            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'),
+            getPeer: createOwnerPeerSource(() => reflectNow()?.get('connection')),
+            listAgents: () => reflectNow()?.get('agents')?.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: () => reflectNow()?.get('sessionQuery'),
+            // 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
@@ -806,42 +1112,7 @@ export function apply(ctx, config = {}) {
             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'),
-                    getPeer: createOwnerPeerSource(() => webCtx.connection),
-                    listAgents: () => webCtx.reflect.get('agents')?.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'),
-                    // 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-
@@ -857,204 +1128,16 @@ export function apply(ctx, config = {}) {
         // 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');
-            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 = () => resolveConfig(config, readFileConfig(), process.env).values.ingressMode;
-            const detectLanAddress = () => {
-                try {
-                    const nets = networkInterfaces();
-                    let tailscaleIp;
-                    let lanIp;
-                    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());
-                    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) => {
-                                    // 模式切换：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, error: 'missing-token' };
-                                    return caddyManager.start({ ...input, cfToken: token });
-                                },
-                                stop: () => caddyManager.stop(),
-                                status: () => (caddyManager.isRunning() ? 'running' : caddyManager.hasStarted() ? 'stopped' : 'never-started'),
-                            },
-                        }),
-                        ...(cloudflaredManager === undefined ? {} : {
-                            tunnel: {
-                                checkDomain: (domain) => runTunnelCheck({ readToken: () => readCfTokenFile(dshHome) }, domain),
-                                setup: (input) => 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());
-                                                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) => {
-                                            if (cloudflaredManager.isRunning())
-                                                cloudflaredManager.stop();
-                                            const started = await cloudflaredManager.start({ tunnelToken: startInput.tunnelToken });
-                                            return started.ok ? { ok: true } : { ok: false, error: started.error ?? 'spawn-failed' };
-                                        },
-                                        // 模式切换：starting the tunnel stops the managed Caddy.
-                                        stopCaddy: () => caddyManager?.stop(),
-                                    },
-                                }, input),
-                                stop: () => cloudflaredManager.stop(),
-                                status: () => (cloudflaredManager.isRunning() ? 'running' : cloudflaredManager.hasStarted() ? 'stopped' : 'never-started'),
-                            },
-                        }),
-                        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;
-                            },
-                        },
-                    }),
+                    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,
@@ -1271,106 +1354,130 @@ export function apply(ctx, config = {}) {
                     getGatewaySummary: gatewaySummary,
                     getProfileName: profileName,
                     getPluginVersion: () => pluginVersion,
+                    lang: resolveActiveLang,
                 }),
             }), 'dsh-zen-remote: client routes (host)');
         });
+        // 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,
+        });
     }
-    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.
+    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;
-        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;
+        const legacyCredentials = () => {
+            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();
+        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 = () => 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;
-        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, client) => 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);
+                        relayPool.queueDeviceNameAll(name);
                 });
                 return () => {
                     off();
@@ -1381,24 +1488,15 @@ export function apply(ctx, config = {}) {
                 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;
+        // 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;
         // T62: the browser's current-session report, held here and read live by
         // the intercept (which cannot reach the browser's localStorage — it
@@ -1406,8 +1504,10 @@ export function apply(ctx, config = {}) {
         // first report arrives the value is `unavailable` and the intercept
         // keeps its conservative tombstone behavior.
         let reportedCurrentSession = { kind: 'unavailable' };
-        const onCurrentSession = (read) => {
+        const onCurrentSession = (read, reportedLang) => {
             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();
@@ -1425,19 +1525,22 @@ export function apply(ctx, config = {}) {
         // 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.
+        // 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();
         const knownRealIds = new Set();
         const rebuildKnownRealIds = () => {
             knownRealIds.clear();
             for (const share of knownSessionShares.values()) {
-                for (const id of share)
+                for (const id of share.ids)
                     knownRealIds.add(id);
             }
         };
-        const createSessionInventorySlot = () => {
+        const createSessionInventorySlot = (serverId) => {
             const slot = {
                 replace(ids) {
-                    knownSessionShares.set(slot, ids);
+                    knownSessionShares.set(slot, { serverId, ids });
                     rebuildKnownRealIds();
                 },
                 dispose() {
@@ -1447,6 +1550,19 @@ export function apply(ctx, config = {}) {
             };
             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) => {
+            const out = new Set();
+            for (const share of knownSessionShares.values()) {
+                if (share.serverId !== serverId)
+                    continue;
+                for (const id of share.ids)
+                    out.add(id);
+            }
+            return out;
+        };
         const interceptDiagnostics = () => {
             if (interceptHandle !== undefined)
                 return interceptHandle.diagnostics();
@@ -1475,9 +1591,14 @@ export function apply(ctx, config = {}) {
             }
             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,
@@ -1572,8 +1693,9 @@ export function apply(ctx, config = {}) {
             }
             // 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('; '));
@@ -1581,8 +1703,14 @@ export function apply(ctx, config = {}) {
             }
             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;
@@ -1650,7 +1778,9 @@ export function apply(ctx, config = {}) {
             }
             // 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
@@ -1671,8 +1801,12 @@ export function apply(ctx, config = {}) {
             }
             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;
@@ -1743,9 +1877,16 @@ export function apply(ctx, config = {}) {
             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
@@ -1770,24 +1911,36 @@ export function apply(ctx, config = {}) {
                     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, probeCtx) => ({
+            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');
         });
     }
@@ -1839,12 +1992,60 @@ export function apply(ctx, config = {}) {
         // 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 !== 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 = {
+            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,
+                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