dsh-zen-remote 2.0.3 → 2.2.0

package/src/client-data/settings-form.ts

@@ -26,6 +26,7 @@
  */
 
 import { RESTART_FIELDS } from '../restart-fields.ts'
+import { derivePluginBridgeStatuses, type PluginBridgeStatusView } from './plugin-bridge.ts'
 
 // --- wire shapes -----------------------------------------------------------
 
@@ -88,6 +89,8 @@ export const ADMIN_STATUS_ROUTE = '/_dsh/zen-remote/admin/status'
 export const ADMIN_PAIR_ROUTE = '/_dsh/zen-remote/admin/pair'
 export const ADMIN_ACTION_ROUTE = '/_dsh/zen-remote/admin/action'
 export const ADMIN_PUSH_TEST_ROUTE = '/_dsh/zen-remote/admin/push-test'
+/** PB-5: the plugin bridge's registered-plugin listing (GET, server-local only). */
+export const ADMIN_PLUGIN_BRIDGE_ROUTE = '/_dsh/zen-remote/admin/plugin-bridge'
 
 /** Same-origin client routes the sub-client block talks to (host half: T16). */
 export const CLIENT_CLAIM_ROUTE = '/_dsh/zen-remote/client/claim'
@@ -153,6 +156,13 @@ export interface ClientStatusBody {
    * string[], unavailable: string[], incompatibleCalls: { time: number,
    * endpoint: string, code: string }[] }` (presence-gated). */
   compat?: unknown
+  /** PB-2: the per-plugin bridge verdicts (`BridgeStatus[]` verbatim,
+   * presence-gated — older servers answer without it). */
+  pluginBridge?: unknown
+  /** PB-4: the plugin-route interception's diagnostics (presence-gated —
+   * a host role or a refused install may still answer it; a server without
+   * the field never does). */
+  pluginRouteIntercept?: unknown
 }
 
 /** One remote-call failure line in the diagnostics lists. `time` is epoch
@@ -200,6 +210,13 @@ export interface ClientConnectionView {
   deviceName: string
   intercept: ClientInterceptView | undefined
   compat: ClientCompatView | undefined
+  /** PB-5: the bridge verdicts as the 诊断区 renders them, input order kept
+   * (undefined when the body carried none — the group stays hidden). */
+  pluginBridge: PluginBridgeStatusView[] | undefined
+  /** PB-5: the route interception's install state (`installed: false`
+   * renders the 本机改道未启用 line with the shape reasons; undefined when
+   * the body carried none). */
+  pluginRouteIntercept: { installed: boolean; reasons: string[] } | undefined
 }
 
 const CLIENT_STATES: readonly ClientConnectionView['state'][] = ['unpaired', 'connected', 'revoked', 'unreachable', 'unexpected', 'invalid-url', 'incompatible']
@@ -258,6 +275,18 @@ function deriveInterceptView(value: unknown): ClientInterceptView | undefined {
   }
 }
 
+/** PB-4 route-interception block, presence-gated the same way: only the
+ * install flag and the shape reasons (the 本机改道未启用 line) — the
+ * counters belong to the status surface, not this copy. */
+function derivePluginRouteInterceptView(value: unknown): { installed: boolean; reasons: string[] } | undefined {
+  if (value === undefined || value === null) return undefined
+  const record = asRecord(value)
+  return {
+    installed: record.installed === true,
+    reasons: stringListOf(record.reasons, 20),
+  }
+}
+
 /** T42 compat block, only when the body carried the field at all. The wire
  * names are the status route's (`different` / `incompatibleCalls`); the view
  * keeps the render-side names the block was written against. */
@@ -302,6 +331,8 @@ export function deriveClientStatusView(body: ClientStatusBody): ClientConnection
     deviceName: typeof safe.deviceName === 'string' ? safe.deviceName : '',
     intercept: deriveInterceptView(safe.intercept),
     compat: deriveCompatView(safe.compat),
+    pluginBridge: derivePluginBridgeStatuses(safe.pluginBridge),
+    pluginRouteIntercept: derivePluginRouteInterceptView(safe.pluginRouteIntercept),
   }
 }
 
@@ -641,6 +672,47 @@ export function boolField(field: string): SettingsFieldSpec {
   }
 }
 
+/**
+ * `pluginBridgeConsent` (PB-5): a name → boolean map staged as its canonical
+ * JSON draft. Nothing renders it as text — the 插件桥 toggles stage the NEXT
+ * map wholesale (`togglePluginConsent` builds it, one key per click) — but
+ * riding the shared spec table is what puts the field on the SAME save path
+ * as `autoShareNewSessions`: one staged revision, one save button, one
+ * atomic mutation. `format` keeps the value's own key order so a staged
+ * draft equal to the displayed value reads as "no change"; an illegal stored
+ * map formats as `{}` (the toggle then writes from scratch, and the junk
+ * stays refused by the row validator, never laundered through).
+ */
+export function consentField(field: string): SettingsFieldSpec {
+  const format = (value: unknown): string => {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) return '{}'
+    const out: Record<string, boolean> = {}
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof entry === 'boolean') out[key] = entry
+    }
+    return JSON.stringify(out)
+  }
+  return {
+    field,
+    format,
+    parse: (text) => {
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(text)
+      } catch {
+        return undefined
+      }
+      if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined
+      const out: Record<string, boolean> = {}
+      for (const [key, entry] of Object.entries(parsed as Record<string, unknown>)) {
+        if (typeof entry !== 'boolean') return undefined
+        out[key] = entry
+      }
+      return { kind: 'set', value: out }
+    },
+  }
+}
+
 /** Names of the row fields the settings page edits, in group order. */
 export type SettingsFieldName =
   | 'role'
@@ -657,6 +729,7 @@ export type SettingsFieldName =
   | 'serverName'
   | 'idleHours'
   | 'autoShareNewSessions'
+  | 'pluginBridgeConsent'
 
 /** Longest legal `serverName`, mirroring src/config.ts's cap. */
 export const SERVER_NAME_MAX = 40
@@ -680,6 +753,7 @@ export const SETTINGS_FIELDS: readonly SettingsFieldSpec[] = [
   nameField('serverName', SERVER_NAME_MAX),
   hoursField('idleHours', IDLE_HOURS_MAX),
   boolField('autoShareNewSessions'),
+  consentField('pluginBridgeConsent'),
 ]
 
 // --- the status -> view mapping ---------------------------------------------
@@ -894,6 +968,10 @@ export interface ZenRemoteFormState extends SettingsFormShellState {
   serverName: SettingsFieldState
   idleHours: SettingsFieldState
   autoShareNewSessions: SettingsFieldState
+  /** The consent map's staged state (PB-5). No text control renders it — the
+   * 插件桥 toggles stage the next map wholesale — but its `invalid` flag
+   * (a malformed draft) still gates the save like any field's. */
+  pluginBridgeConsent: SettingsFieldState
   deviceToken: SettingsSecretFieldState
   /** A restart-required field ({@link RESTART_FIELDS}) has a staged change a
    * save would actually write: the save will move the row and the host

package/src/client-routes.ts

@@ -31,7 +31,9 @@ import type { ClaimOutcome, ProbeState } from './client-pairing.js'
 import { unwrapVolatile } from './config.js'
 import type { FetchRouteInterceptDiagnostics } from './fetch-route-intercept.js'
 import type { CurrentSessionRead, InterceptDiagnostics } from './intercept.js'
+import type { PluginRouteInterceptDiagnostics } from './plugin-route-intercept.js'
 import { responseJson, sameOriginPost } from './http.js'
+import type { BridgeStatus } from './plugin-bridge.js'
 import { RELAY_HTTP_ROUTES } from './relay-access.js'
 import { relayCredentialsDigest, RelayError } from './relay-client.js'
 import type { RelayClient, RelayHttpResult } from './relay-client.js'
@@ -118,6 +120,17 @@ export interface ClientHandlerOptions {
    * its refusal counters. Undefined when this composition never attempted
    * one (no connection service, or no fileUploads service to inject). */
   getFetchRouteIntercept?: () => FetchRouteInterceptDiagnostics | undefined
+  /** The plugin-route interception's diagnostics (PB-4), read live per
+   * request: the local webServer `match` wrap that forwards bridged-plugin
+   * requests for remote sessions. Undefined when this composition never
+   * attempted one (a host role, or no webServer). */
+  getPluginRouteIntercept?: () => PluginRouteInterceptDiagnostics | undefined
+  /** The plugin bridge's live verdict (PB-2), computed PER CALL off the local
+   * registry, the last handshake's `plugins` table and the connection state —
+   * never a stored conclusion. Wired only by the CLIENT role's mount; absent
+   * (the host mount, old tests) both routes answer the empty shape: status's
+   * `pluginBridge: []` and remote-status's `bridgedPlugins: []`. */
+  getPluginBridgeStatus?: () => BridgeStatus[]
   /** Serve ONLY the remote-status route (T41a-fix2, the host role's mount):
    * every other route under the prefix answers the same 404 an unknown path
    * would. The claim / status / reconnect / unshare routes exist for a
@@ -456,6 +469,7 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
         // that.
         const intercept = options.getIntercept?.()
         const fetchRouteIntercept = options.getFetchRouteIntercept?.()
+        const pluginRouteIntercept = options.getPluginRouteIntercept?.()
         const compatRelay = options.getRelayClient?.()
         const compat =
           compatRelay?.compat !== undefined || (intercept?.incompatibleCalls.length ?? 0) > 0
@@ -467,8 +481,13 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
               }
             : undefined
         const withDiagnostics = (body: Record<string, unknown>): Record<string, unknown> => {
-          let next = intercept === undefined ? body : { ...body, intercept }
+          // PB-2: the per-plugin bridge verdict rides EVERY status answer —
+          // the settings surface explains a not-bridged plugin whatever the
+          // connection state (unpaired reads all-offline, the honest verdict).
+          let next: Record<string, unknown> = { ...body, pluginBridge: options.getPluginBridgeStatus?.() ?? [] }
+          if (intercept !== undefined) next = { ...next, intercept }
           if (fetchRouteIntercept !== undefined) next = { ...next, fetchRouteIntercept }
+          if (pluginRouteIntercept !== undefined) next = { ...next, pluginRouteIntercept }
           return compat === undefined ? next : { ...next, compat }
         }
         // The ROW decides its own two shapes first, per request (both fields
@@ -571,6 +590,11 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
         // T34: the T34 client parts' data source — no token, no server
         // address, nothing but the serving state, the compat verdict's
         // difference flag, the display name and the closed-session map.
+        // PB-2 adds `bridgedPlugins`: the names whose bridge verdict is
+        // bridged RIGHT NOW, sorted (the list arrives plugin-sorted, but the
+        // sort is pinned here so the field's shape never depends on the
+        // registry's internal order). The host mount — no verdict source —
+        // answers [].
         const relay = options.getRelayClient?.()
         const intercept = options.getIntercept?.()
         responseJson(res, 200, {
@@ -578,6 +602,10 @@ export function createClientHandler(options: ClientHandlerOptions): ClientHandle
           versionMismatch: (relay?.compat?.different?.length ?? 0) > 0,
           serverName: relay?.handshakeInfo?.serverName ?? '',
           closed: Object.fromEntries((intercept?.closedSessions ?? []).map((record) => [record.sessionId, record.reason])),
+          bridgedPlugins: (options.getPluginBridgeStatus?.() ?? [])
+            .filter((status) => status.bridged)
+            .map((status) => status.plugin)
+            .sort(),
         })
         return
       }

package/src/config.ts

@@ -77,6 +77,12 @@ export interface ZenRemoteConfig {
   idleHours: number
   /** Auto-share every newly created session to the paired phone (T16). */
   autoShareNewSessions: boolean
+  /** Per-plugin consent for bridging whole-machine data (plugin bridge,
+   * PB-1): plugin name → whether the server owner lets that plugin's
+   * `scope:'server'` routes be forwarded inside remote sessions. Absent or
+   * false means NO — default `{}` keeps every plugin unconsented. Volatile:
+   * read at compare time, deliberately NOT in RESTART_FIELDS. */
+  pluginBridgeConsent: Record<string, boolean>
 }
 
 function defaultServerName(): string {
@@ -101,6 +107,7 @@ export const DEFAULTS: ZenRemoteConfig = {
   serverName: defaultServerName(),
   idleHours: 48,
   autoShareNewSessions: false,
+  pluginBridgeConsent: {},
 }
 
 // --- per-field validators -------------------------------------------------
@@ -176,6 +183,22 @@ function serverNameOf(value: unknown): string | undefined {
   return name === undefined ? undefined : name.slice(0, SERVER_NAME_MAX)
 }
 
+/** `pluginBridgeConsent`: a plain object mapping plugin names to STRICT
+ * booleans. Anything else — null, an array, a non-boolean value (`"yes"`,
+ * `1`; unlike the scalar booleans there is no historic `1`/`"1"` convention
+ * to honor, this map only ever came from the settings surface or a
+ * hand-edited row/file) — makes the layer transparent, because a half-valid
+ * consent map must never read as "consented". Object keys are strings by
+ * construction in both JSON and YAML; the per-key string check stays as the
+ * cheap belt over the iteration. */
+function consentMap(value: unknown): Record<string, boolean> | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof key !== 'string' || typeof entry !== 'boolean') return undefined
+  }
+  return value as Record<string, boolean>
+}
+
 /** Env validator applied to `Number(env[name])`, so `LAN_GATE_PORT='abc'`
  * lands in the same "unset" bucket as a bad row value. */
 function envNumber(
@@ -263,6 +286,10 @@ const FIELDS: { [K in keyof ZenRemoteConfig]: FieldResolver<ZenRemoteConfig[K]>
   serverName: { row: serverNameOf, file: serverNameOf },
   idleHours: { row: inRange(0, 8760), file: inRange(0, 8760) },
   autoShareNewSessions: { row: boolLike, file: boolLike },
+  // No env layer on purpose (PB-1): a per-plugin consent map has no historic
+  // flat variable to stay compatible with, and a consent decision is a
+  // settings-page action, not something set through the environment.
+  pluginBridgeConsent: { row: consentMap, file: consentMap },
 }
 
 /**
@@ -346,6 +373,7 @@ export function resolveConfig(
     serverName: resolveField('serverName', safeRow, safeFile, env, sources),
     idleHours: resolveField('idleHours', safeRow, safeFile, env, sources),
     autoShareNewSessions: resolveField('autoShareNewSessions', safeRow, safeFile, env, sources),
+    pluginBridgeConsent: resolveField('pluginBridgeConsent', safeRow, safeFile, env, sources),
   }
   return { values, sources }
 }
@@ -432,6 +460,10 @@ export const Config = z.object({
   serverName: z.any().volatile(),
   idleHours: z.any().volatile(),
   autoShareNewSessions: z.any().volatile(),
+  // Plugin-bridge consent (PB-1): a name → boolean map, live-read at compare
+  // time — a consent flip must apply without a row restart, so it is
+  // deliberately NOT in RESTART_FIELDS.
+  pluginBridgeConsent: z.any().volatile(),
   // Client-half knobs (T16): where the phone finds the gateway, and the
   // pairing token it presents. `role('secret')` keeps the token out of every
   // settings wire surface, like the verifier plugin's API key.

package/src/http.ts

@@ -66,3 +66,15 @@ export function sameOriginPost(req: IncomingMessage): boolean {
     return false
   }
 }
+
+
+/**
+ * One plugin-bridge refusal (PB-3): the standard JSON envelope plus the
+ * `x-zen-remote-error` marker header — the sub-client's passthrough layer
+ * classifies a refusal off the header alone, because the success path
+ * streams opaque plugin bytes and must never have to parse a body.
+ */
+export function pluginBridgeError(res: ServerResponse, status: number, code: string): void {
+  res.setHeader('x-zen-remote-error', code)
+  responseJson(res, status, { ok: false, error: { code } })
+}

package/src/index.ts

@@ -59,8 +59,22 @@ import { checkGatewayShape } from './intercept-shape.js'
 import type { GatewayShapeCheck } from './intercept-shape.js'
 import { checkFetchRouteShape, installFetchRouteIntercept } from './fetch-route-intercept.js'
 import type { FetchRouteInterceptDiagnostics, FetchRouteInterceptHandle, FetchRouteShapeCheck } from './fetch-route-intercept.js'
+import { checkWebServerShape, installPluginRouteIntercept } from './plugin-route-intercept.js'
+import type { PluginRouteInterceptDiagnostics, PluginRouteInterceptHandle, WebServerShapeCheck } from './plugin-route-intercept.js'
+import { normalizeAdapter, adapterOwnsRegistryEntry } from './plugin-adapter-core.js'
+import type { NormalizedAdapter } from './plugin-adapter-core.js'
+import { ADAPTERS } from './adapters/index.js'
 import { createRelayHandler, loadServerId, RELAY_PREFIX, resolveDshVersion } from './relay-server.js'
 import type { RelayGateway, RelayHandler } from './relay-server.js'
+import { createBridgeRegistry, compareBridges } from './plugin-bridge.js'
+import type { BridgeDeclaration, BridgeRegistry, BridgeStatus, ServerPluginEntry, ZenRemoteService } from './plugin-bridge.js'
+import { createPluginLoopback } from './plugin-loopback.js'
+import { createPluginTunnel } from './plugin-tunnel.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
+// lib/types. Type-only: no runtime code, no Context augmentation.
+export type { BridgeDeclaration, ZenRemoteService } from './plugin-bridge.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
@@ -126,6 +140,22 @@ export function getRelayClient(): RelayClient | undefined {
   return clientRelayClient
 }
 
+/**
+ * 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
+ * table, the client-side rewrite) can reach it without reaching into a
+ * context. Undefined in compositions that never ran this module's apply, and
+ * — identity-guarded below — after the row that owned a registry was
+ * unloaded or reloaded, so a reloaded row never leaves a stale table where
+ * the getter can hand it out (the T23a-fix discipline).
+ */
+let bridgeRegistry: BridgeRegistry | undefined
+
+/** The live bridge registry, if a plugin row is currently applied. */
+export function getBridgeRegistry(): BridgeRegistry | undefined {
+  return bridgeRegistry
+}
+
 /** Host half config. Every field below arrives through the loader as a
  * volatile live reference — a `{ get() }` wrapper over the stored value, not
  * the value itself (src/config.ts explains why every field is volatile) — so
@@ -461,6 +491,76 @@ export async function handleUpload(
  */
 export function apply(ctx: Context, config: MobileNavConfig = {}): void {
   const effective = resolveConfig(config, readFileConfig(), process.env)
+  // The plugin bridge's zenRemote service (PB-1), provided on BOTH roles
+  // before any role branch: a plugin that wants its panel data forwarded in
+  // remote sessions declares that against THIS process whichever role it
+  // runs as, and the declaration registry is the one piece of PB-1 both the
+  // server half (handshake plugins table) and the client half (route
+  // rewrite) will read. ctx.provide (cordis 4) registers the service owned
+  // by THIS row's fiber: visible to `inject(['zenRemote'])` dependents once
+  // the row is active, withdrawn when the row unloads — so a composition
+  // without zen-remote never fires those injects and a row reload swaps the
+  // service wholesale. The registry goes into the module slot BEFORE the
+  // provide so this apply's consumers never see a window without it; the
+  // effect's identity guard then clears the slot exactly when THIS row
+  // unloads (a reload installs the new registry before the old disposer
+  // runs, same shape as clientRelayClient). provide() throwing is not worth
+  // failing the row over — the bridge stays off, everything else keeps
+  // working — so it degrades to a warning like the session feeds do.
+  const registry = createBridgeRegistry({
+    warn: (text) => { ctx.logger?.warn('dsh-zen-remote plugin bridge: %s', text) },
+  })
+  bridgeRegistry = registry
+  try {
+    const service: ZenRemoteService = {
+      bridge: (declaration: BridgeDeclaration) => registry.register(declaration),
+    }
+    ctx.provide('zenRemote', service)
+  } catch (error) {
+    ctx.logger?.warn('dsh-zen-remote: cannot provide the "zenRemote" service: %s', message(error))
+  }
+  ctx.effect(() => () => {
+    if (bridgeRegistry === registry) bridgeRegistry = undefined
+  }, 'dsh-zen-remote: plugin bridge registry disposal')
+  // The adapters (PB-11): each one registers ONLY against its target's
+  // EXACT installed version, probed off the host's `pluginPackages` service
+  // (`packageOf(name, ctx.baseUrl)` — verified on 0.2.0-rc.2 to answer
+  // `{name, version, dir, …}` or undefined; any other shape, a missing
+  // service or a probe failure reads as "not installed" and the adapter
+  // stays out). A plugin that registers its OWN cooperative declaration
+  // always wins: the adapter yields at registration time (logged), and the
+  // runtime re-checks the registry digest on every request. Both roles run
+  // this loop — the registry entries drive the handshake table, the bridge
+  // verdicts and the settings listing on either side, while the returned
+  // array feeds the two request halves.
+  const adapters: NormalizedAdapter[] = []
+  {
+    const adapterWarn = (text: string): void => { ctx.logger?.warn('dsh-zen-remote adapter: %s', text) }
+    for (const adapter of ADAPTERS) {
+      try {
+        const holder = ctx as unknown as { get?: (name: string) => unknown; baseUrl?: string }
+        const packages = holder.get?.('pluginPackages') as { packageOf?: (specifier: string, parentURL: string) => unknown } | undefined
+        const found = packages?.packageOf?.(adapter.plugin, holder.baseUrl ?? '') as { version?: unknown } | undefined
+        const installedVersion = found !== null && typeof found === 'object' && typeof (found as { version?: unknown }).version === 'string'
+          ? (found as { version: string }).version
+          : undefined
+        if (installedVersion === undefined || installedVersion === '') {
+          adapterWarn(`${adapter.plugin}: target package (or its version) not found; not registered`)
+          continue
+        }
+        const normalized = normalizeAdapter(adapter, installedVersion)
+        if (registry.get(normalized.plugin) !== undefined) {
+          adapterWarn(`${normalized.plugin}: the plugin registers its own bridge declaration; the adapter yields`)
+          continue
+        }
+        registry.registerNormalized(normalized.declaration)
+        adapters.push(normalized)
+        ctx.logger?.info('dsh-zen-remote adapter: %s adapted at version %s', normalized.plugin, installedVersion)
+      } catch (error) {
+        adapterWarn(`${adapter.plugin} refused: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+  }
   if (effective.values.role === 'host') {
     // A row that switched from client to host must not leave a stale relay
     // client where getRelayClient() can find it (T23a-fix).
@@ -597,6 +697,16 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           // 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)),
+          },
         }),
       }), 'dsh-zen-remote: admin routes')
     })
@@ -645,6 +755,32 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       // ~7 ms per computation against a full registry; a failed compute
       // lands as the empty map inside the relay handler's own guard.
       relayCtx.effect(() => {
+        // The plugin bridge's loopback facts (PB-3), both read PER REQUEST
+        // through the reflection layer: the web server may have restarted on
+        // another port or protocol, and the connection service's
+        // authenticatedUrl — the token-exchange entry the lan-gate wiring
+        // also reads (0.1.1 hosts lack the method entirely) — lives on a
+        // service deliberately NOT in this inject's declaration list (same
+        // reason as getApiFetch above: adding it would keep the whole relay
+        // prefix off compositions that lack it).
+        const getLoopbackTarget = () => {
+          const webServer = relayCtx.reflect.get('webServer') as { protocol?: unknown; port?: unknown } | undefined
+          const port = typeof webServer?.port === 'number' && webServer.port > 0 ? webServer.port : undefined
+          if (port === undefined) throw new Error('the web server exposes no loopback port')
+          return { protocol: webServer?.protocol === 'https:' ? ('https:' as const) : ('http:' as const), port }
+        }
+        const getTokenUrl = () => {
+          const connection = relayCtx.reflect.get('connection') as
+            | { authenticatedUrl?: (base: string) => string | undefined }
+            | undefined
+          if (typeof connection?.authenticatedUrl !== 'function') return undefined
+          const { protocol, port } = getLoopbackTarget()
+          return connection.authenticatedUrl(`${protocol}//127.0.0.1:${port}`)
+        }
+        // One loopback executor for BOTH plugin halves (the HTTP forward and
+        // the PB-10 tunnel): a single cookie cache behind two consumers.
+        const pluginLoopback = createPluginLoopback({ getTarget: getLoopbackTarget, getTokenUrl })
+        const pluginConsent = () => resolveConfig(config, readFileConfig(), process.env).values.pluginBridgeConsent
         const handler = createRelayHandler({
           secret: relaySecret,
           store,
@@ -662,6 +798,43 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
             serverName: () => resolveConfig(config, readFileConfig(), process.env).values.serverName,
             dshVersion: resolveDshVersion(),
             fingerprints: () => computeFingerprints(relayCtx),
+            // PB-2: the plugin bridge table, rebuilt FRESH at every handshake
+            // from the PB-1 registry and the row's consent map — both live:
+            // the registry through this apply's own closure, the consent
+            // through resolveConfig on the SAME row object (a volatile field,
+            // read at use time per the hard constraint, never snapshotted).
+            plugins: () => {
+              const consent = resolveConfig(config, readFileConfig(), process.env).values.pluginBridgeConsent
+              const table: Record<string, ServerPluginEntry> = {}
+              for (const declaration of registry.list()) {
+                table[declaration.plugin] = {
+                  version: declaration.version,
+                  digest: declaration.digest,
+                  serverScopeConsent: consent[declaration.plugin] === true,
+                }
+              }
+              return table
+            },
+          },
+          // PB-3: the forwarding half of the plugin bridge — the registry
+          // this apply built (the zenRemote service's table), the consent
+          // map read LIVE per request (a volatile row field), and the
+          // loopback executor over the wiring's two reflection getters.
+          // PB-10: the WebSocket byte tunnel's server half shares the SAME
+          // loopback (one cookie cache) and the same live consent; its
+          // reachability judgment rides the store directly (the handler's
+          // own isAccessible closure is not visible out here).
+          pluginBridge: {
+            registry,
+            getConsent: pluginConsent,
+            loopback: pluginLoopback,
+            adapters,
+            tunnel: createPluginTunnel({
+              bridge: { registry, getConsent: pluginConsent, loopback: pluginLoopback },
+              getTarget: getLoopbackTarget,
+              isAccessible: (sessionId) => store.isAccessible(sessionId, parentIndex.parentOf),
+              heartbeatMs: 15_000,
+            }),
           },
         })
         const unregister = relayCtx.webServer.register({
@@ -735,6 +908,15 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       computeOwnFingerprints: () => computeFingerprints(ctx),
     })
     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
+    // CALL (never a stored conclusion): the local registry is this apply's
+    // own closure, the server's table is the 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
+    // 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')
     // 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
@@ -931,6 +1113,74 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
         if (fetchRouteHandle === handle) fetchRouteHandle = undefined
       }, 'dsh-zen-remote: fetch-route intercept')
     })
+    // The plugin bridge's route interception (PB-4): the local webServer's
+    // `match` wrap forwarding bridged-plugin requests for REMOTE sessions
+    // through the relay. Injected on `webServer` alone — the only service
+    // it reads — and the raw instance comes off the reflection layer's
+    // symbols lookup, the same face the typert and fetch-route wraps use.
+    // The diagnostics flow to the client status route like theirs, refused
+    // installs included.
+    let pluginRouteHandle: PluginRouteInterceptHandle | undefined
+    let pluginRouteRefused: WebServerShapeCheck | undefined
+    const pluginRouteDiagnostics = (): PluginRouteInterceptDiagnostics | undefined => {
+      if (pluginRouteHandle !== undefined) return pluginRouteHandle.diagnostics()
+      if (pluginRouteRefused !== undefined) {
+        return {
+          installed: false,
+          shape: pluginRouteRefused,
+          forwarded: 0,
+          refused: 0,
+          refusalsByReason: {},
+          recentFailures: [],
+          adapterForwarded: 0,
+          adapterResponseRewrites: 0,
+          adapterResponsePassthroughs: 0,
+          tunnelsCurrent: 0,
+          tunnelsOpened: 0,
+          tunnelsClosed: 0,
+        }
+      }
+      return undefined
+    }
+    ctx.inject(['webServer'], (wsCtx) => {
+      const logWarn = (...args: Parameters<Context['logger']['warn']>): void => { ctx.logger?.warn(...args) }
+      const proxy = (wsCtx as Context & { webServer?: unknown }).webServer
+      const raw = proxy !== null && typeof proxy === 'object'
+        ? (proxy as unknown as Record<PropertyKey, unknown>)[symbols.original]
+        : undefined
+      if (raw === null || typeof raw !== 'object') {
+        pluginRouteRefused = { ok: false, reasons: ['original: webServer[symbols.original] is not an object'] }
+        logWarn('dsh-zen-remote plugin-route intercept not installed: %s', pluginRouteRefused.reasons[0])
+        return
+      }
+      // Shape first, like every wrap: a failed check leaves the webServer
+      // exactly as it was — local routing untouched, remote bridging off.
+      const shape = checkWebServerShape(raw)
+      if (!shape.ok) {
+        pluginRouteRefused = shape
+        logWarn('dsh-zen-remote plugin-route intercept not installed: %s', shape.reasons.join('; '))
+        return
+      }
+      const handle = installPluginRouteIntercept({
+        webServer: raw,
+        registry,
+        relay: relayClient,
+        getServerId: () => relayClient.handshakeInfo?.serverId,
+        getStatus: pluginBridgeStatus,
+        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
+        // routes' deny hooks read (better-sidebar's open.external carries
+        // no session field of its own).
+        getCurrentSession: () => (reportedCurrentSession.kind === 'open' ? reportedCurrentSession.sessionId : undefined),
+        log: (format, ...args) => { ctx.logger?.info(`dsh-zen-remote ${format}`, ...args) },
+      })
+      pluginRouteHandle = handle
+      wsCtx.effect(() => () => {
+        handle.uninstall()
+        if (pluginRouteHandle === handle) pluginRouteHandle = undefined
+      }, 'dsh-zen-remote: plugin route intercept')
+    })
     ctx.inject(['webServer', 'connection'], (clientCtx) => {
       clientCtx.effect(() => clientCtx.webServer.register({
         kind: 'prefix',
@@ -941,6 +1191,8 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           getRelayClient: () => relayClient,
           getIntercept: interceptDiagnostics,
           getFetchRouteIntercept: fetchRouteDiagnostics,
+          getPluginRouteIntercept: pluginRouteDiagnostics,
+          getPluginBridgeStatus: pluginBridgeStatus,
           onCurrentSession,
         }),
       }), 'dsh-zen-remote: client routes')