dsh-zen-remote 2.0.2 → 2.2.0

package/scripts/check-settings-form.mjs

@@ -456,7 +456,9 @@ test('the latest-wins gate drops tickets that are no longer newest (T15-fix 4)',
 
 test('deriveClientStatusView maps every probe state and tolerates garbage', () => {
   // T59: the view carries the device's own name ('' when the body had none).
-  const bare = { state: 'unpaired', serverUrl: '', serverName: '', deviceName: '', nextRetryAt: undefined, lastError: '', intercept: undefined, compat: undefined }
+  // PB-5: the bridge rows ([] — the body carried none) and the rerouting
+  // note (undefined) ride the same tolerant derivation.
+  const bare = { state: 'unpaired', serverUrl: '', serverName: '', deviceName: '', nextRetryAt: undefined, lastError: '', intercept: undefined, compat: undefined, pluginBridge: [], pluginRouteIntercept: undefined }
   assert.deepEqual(deriveClientStatusView({ state: 'unpaired' }), bare)
   assert.deepEqual(deriveClientStatusView({ state: 'connected', serverUrl: 'http://192.168.1.10:3088' }), {
     ...bare,

package/src/adapters/dsh-better-sidebar/index.ts

@@ -0,0 +1,144 @@
+/**
+ * The dsh-better-sidebar adapter (PB-12), written against EXACTLY
+ * version 0.25.0. Everything it knows about the plugin came off
+ * `/tmp/bs-versions/0.25.0/lib/index.js` (the installed copy at
+ * `~/.dsh/profiles/desktop/node_modules/dsh-better-sidebar` is the same
+ * build); the method table lives in `methods.ts` beside this file, and the
+ * test suite re-extracts the plugin's real method-name set to catch a
+ * silently drifted version.
+ *
+ * Product decisions (2026-10-10): reads AND writes both forward — a
+ * bridged better-sidebar is whole-server disk access, git writes, and
+ * model spend (commit-message generation), documented as such; NO path
+ * fencing; `open.external` refuses for a remote session; `settings.*` and
+ * `/sidebar/bundle` stay local; the adapter registers as whole-machine
+ * data (consent per plugin, default off).
+ *
+ * The `cwd` handling is the one subtle part: better-sidebar resolves a
+ * request's working directory as the session's own `header.cwd` first and
+ * only falls back to a `cwd` field the CLIENT supplied (lib/index.js:6295,
+ * 6075-6099). A remote panel must not steer the server by path, so the
+ * server hook strips `cwd` — from the JSON body (`/sidebar/api`) and from
+ * the query (`/sidebar/file`, `/sidebar/upload`) — and lets the backend
+ * resolve from the (validated, real) session id.
+ */
+
+import type { BridgeAdapter } from '../types.js'
+import { isVirtual } from '../../virtual-id.js'
+import { SIDEBAR_METHODS, sidebarMethodNameOf } from './methods.js'
+
+/** The relay's upload budget (`MAX_UPLOAD_BYTES` in lib/relay-server.js).
+ * Inlined rather than imported — an adapter may only lean on pure utility
+ * modules — and pinned to the original by a test in
+ * test/adapter-better-sidebar.test.cjs, which fails the pair apart when
+ * either side moves. */
+const RELAY_UPLOAD_CAP_BYTES = 100 * 1024 * 1024
+
+/** better-sidebar's own JSON body bound (lib/index.js:863
+ * `MAX_BODY_BYTES = 1 << 20`) — the adapter forwards at most what the
+ * backend would accept anyway. */
+const SIDEBAR_MAX_BODY_BYTES = 1024 * 1024
+
+/** The method name out of a `/sidebar/api/*` pathname, or `''`. */
+const apiMethodOf = (pathname: string): string => sidebarMethodNameOf(pathname) ?? ''
+
+export const dshBetterSidebarAdapter: BridgeAdapter = {
+  plugin: 'dsh-better-sidebar',
+  versions: ['0.25.0'],
+  routes: [
+    {
+      // The JSON API: the method name rides the path tail, the session
+      // fields ride the body top level (sessionId / rootSessionId /
+      // childId — the sidechat calls).
+      path: '/sidebar/api',
+      match: 'prefix',
+      methods: ['POST'],
+      maxBody: SIDEBAR_MAX_BODY_BYTES,
+      locator: { in: 'json-body', fields: ['sessionId', 'rootSessionId', 'childId'] },
+      deny: ({ pathname, currentSessionId }) => {
+        const name = apiMethodOf(pathname)
+        if (name === '') return undefined
+        // Opening apps/URLs on the HOST is a remote-panel no: refused when
+        // the browser is currently looking at a REMOTE session (the
+        // request body carries no session field of its own — client.js
+        // 9383-9392 — so the classify step could never tell). A LOCAL
+        // session's open.external never reaches here as a refusal and
+        // stays on the local machine, exactly as without zen-remote.
+        // (The sidechat methods left this hook in PB-13: their child
+        // sessions inherit the parent's share through `meta.parentSession`,
+        // so they forward like everything else.)
+        if (name === 'open.external' && currentSessionId !== undefined && isVirtual(currentSessionId)) {
+          return 'remote-open-unsupported'
+        }
+        return undefined
+      },
+    },
+    // The media route: better-sidebar registers a PREFIX, the adapter only
+    // claims the EXACT documented path — a sub-path (if a future version
+    // grows one) stays local rather than being guessed at.
+    { path: '/sidebar/file', match: 'exact', methods: ['GET'], locator: { in: 'query', name: 'sessionId' } },
+    // The archive download (lib/index.js:6949-6985).
+    { path: '/sidebar/archive', match: 'exact', methods: ['GET'], locator: { in: 'query', name: 'sessionId' } },
+    // The raw upload (lib/index.js:6905-6948): binary bytes, capped by the
+    // relay's own upload budget.
+    { path: '/sidebar/upload', match: 'exact', methods: ['POST'], maxBody: RELAY_UPLOAD_CAP_BYTES, locator: { in: 'query', name: 'sessionId' } },
+    // The HTML preview (lib/index.js:7026+): the session id is the FIRST
+    // path segment after the prefix; the rest of the segments are the
+    // preview file's relative path. Same-prefix relative resources ride
+    // along (they hit the same prefix route with the same segment layout).
+    { path: '/sidebar/html', match: 'prefix', methods: ['GET'], locator: { in: 'path-segment', index: 0 } },
+    // Lazy chunks: client code, session-independent, LOCAL forever.
+    { path: '/sidebar/bundle', match: 'prefix', methods: ['GET'], locator: { in: 'query', name: 'sessionId' }, local: true },
+    // The two WebSockets (PB-13, both `registerUpgrade` EXACT registrations
+    // in lib/index.js:7066-7091): the agent-opens push feed and the
+    // file-tree watch. Both carry the session id in the query; both ride
+    // PB-10's byte tunnel untouched — neither side parses frames, and the
+    // messages need no rewriting (agent-opens pushes carry the server-real
+    // sessionId but the browser never reads it — client.js:23618-23640
+    // uses its own connect-time id for the scope; fs-watch frames carry
+    // file paths, not session ids).
+    { path: '/sidebar/ws/agent-opens', match: 'exact', methods: ['GET'], upgrade: true, locator: { in: 'query', name: 'sessionId' } },
+    { path: '/sidebar/ws/fs-watch', match: 'exact', methods: ['GET'], upgrade: true, locator: { in: 'query', name: 'sessionId' } },
+  ],
+  client: {
+    request: (ctx) => {
+      const name = apiMethodOf(ctx.pathname)
+      // Belt over the deny hook's suspenders: a refused method refuses
+      // even if a future plugin version starts carrying session fields
+      // on it (which would flip it into the remote branch).
+      if (name === 'open.external') return { allow: false, reason: 'remote-open-unsupported' }
+      // Unknown method: refuse — never guess what a drifted version means.
+      if (name !== '' && SIDEBAR_METHODS[name] === undefined) return { allow: false, reason: 'adapter-method-unknown' }
+      return { allow: true }
+    },
+    response: (ctx) => {
+      const name = apiMethodOf(ctx.pathname)
+      if (name === '') return ctx.body
+      const spec = SIDEBAR_METHODS[name]
+      if (spec === undefined || spec.rewrite === undefined) return ctx.body
+      return spec.rewrite(ctx.body, ctx)
+    },
+  },
+  server: {
+    request: (ctx) => {
+      // Strip the client-supplied cwd: the backend resolves the working
+      // directory from the (already validated) session id's own header,
+      // falling back to the persisted record — a remote panel never
+      // steers the server by path.
+      if (ctx.pathname === '/sidebar/file' || ctx.pathname === '/sidebar/upload') {
+        if (ctx.query.get('cwd') !== null) {
+          const stripped = new URLSearchParams(ctx.query)
+          stripped.delete('cwd')
+          return { allow: true, query: stripped }
+        }
+        return { allow: true }
+      }
+      if (ctx.route.path === '/sidebar/api' && ctx.body !== null && typeof ctx.body === 'object' && !Array.isArray(ctx.body) && 'cwd' in (ctx.body as Record<string, unknown>)) {
+        const stripped = { ...(ctx.body as Record<string, unknown>) }
+        delete stripped.cwd
+        return { allow: true, body: stripped }
+      }
+      return { allow: true }
+    },
+  },
+}

package/src/adapters/dsh-better-sidebar/methods.ts

@@ -0,0 +1,215 @@
+/**
+ * better-sidebar 0.25.0 的 `/sidebar/api` 方法表（PB-12）——适配器唯一
+ * 认识的接口清单，逐条对着 `/tmp/bs-versions/0.25.0/lib/index.js` 复核
+ * （行号见各条注释，以 0.25.0 的构建产物为准）。表里没有的方法在远程
+ * 会话里一律拒绝（reason `adapter-method-unknown`）：宁可少转发，不可
+ * 误转发——`test/adapter-better-sidebar.test.cjs` 会把源码里的实际方法
+ * 名集合提取出来与这张表逐一比对，防止插件升级后漏记。
+ *
+ * 会话字段：绝大多数方法在 JSON 体顶层带 `sessionId`（client.js 的
+ * scopePayload，lib/client.js:3866）；子代理与工作流面板带
+ * `rootSessionId`；sidechat 的后续调用带 `childId`（本单一律拒绝）。
+ *
+ * 响应里带会话 id 的位置（核实于 0.25.0 源码，全部只有三处）：
+ *  - `session.cwd` 把请求的 `sessionId` 原样回显（lib/index.js:6327）；
+ *  - `subagents.live` 的响应以会话 id 为键（lib/index.js:4513
+ *    `live[sessionId] = view`，根会话与全部子会话）；
+ *  - `workflows.list` 的每行 `originSessionId`（lib/index.js:4666）与
+ *    `phases[].members[].childId`（lib/index.js:4686）。
+ * `teams.taskCreate`/`taskUpdate` 的响应是 `{ok, value:<任务记录>}`
+ * （lib/index.js:4607-4612、4650-4655），任务记录不带会话 id；
+ * `changes.ops` 返回 `{events, lastSeq}`，事件属于该会话自身的流
+ * （tool/call、tool/result），对象上没有会话 id 字段；
+ * `archive.build` 返回 `{id, entries}`（lib/index.js:3470-3473）、
+ * `archive.status` 返回 `{state, done, total, bytes, error?}`
+ * （lib/index.js:3479-3485）——都不带会话 id。这四类不改写。
+ * `sidechat.start` 返回 `{childId}`（lib/index.js:5050）——PB-13 起
+ * 虚拟化（子客户端拿它发后续调用）。
+ */
+
+/** 响应改写器的上下文（框架的 AdapterResponseContext 的结构性子集）。 */
+export interface SidebarRewriteContext {
+  virtualize(id: string): string
+  isVirtual(value: unknown): boolean
+}
+
+/** 一个 `/sidebar/api` 方法的处置。 */
+export interface SidebarMethodSpec {
+  /** 该方法在 JSON 体顶层的会话字段名（settings.* 无会话字段，缺省）。 */
+  sessionField?: 'sessionId' | 'rootSessionId' | 'childId'
+  /** 读还是写（写方法在远程会话里执行的是主服务端的磁盘与 git）。 */
+  kind: 'read' | 'write'
+  /** 无会话数据的方法（settings.*）：定位结果为空，天然留本机。 */
+  local?: true
+  /** 响应改写器：把响应里的真实会话 id 换回虚拟 id。 */
+  rewrite?: (body: unknown, ctx: SidebarRewriteContext) => unknown
+}
+
+/** 无改写的普通转发方法的简写工厂。 */
+const forward = (kind: 'read' | 'write', sessionField: 'sessionId' | 'rootSessionId' | 'childId' = 'sessionId'): SidebarMethodSpec => ({ kind, sessionField })
+
+/** 0.25.0 的全部方法。 */
+export const SIDEBAR_METHODS: Readonly<Record<string, SidebarMethodSpec>> = {
+  // ---- 会话（lib/index.js:6319-6333）----
+  'session.phase': forward('read'),
+  'session.cwd': {
+    kind: 'read',
+    sessionField: 'sessionId',
+    // 请求的 sessionId 原样回显（lib/index.js:6327）。
+    rewrite: (body, ctx) => rewriteTopLevel(body, 'sessionId', ctx),
+  },
+
+  // ---- 文件（lib/index.js:6334-6442）----
+  'fs.tree': forward('read'),
+  'fs.trees': forward('read'),
+  'fs.search': forward('read'),
+  'fs.read': forward('read'),
+  'fs.write': forward('write'),
+  'fs.rename': forward('write'),
+  'fs.mkdir': forward('write'),
+  'fs.createFile': forward('write'),
+  'fs.remove': forward('write'),
+
+  // ---- git（lib/index.js:6443-6613）----
+  'git.worktrees': forward('read'),
+  'git.status': forward('read'),
+  'git.diff': forward('read'),
+  'git.diff-head': forward('read'),
+  'git.branch': forward('read'),
+  'git.log': forward('read'),
+  'git.commit-diff': forward('read'),
+  'git.show': forward('read'),
+  'git.blame': forward('read'),
+  'git.stage': forward('write'),
+  'git.unstage': forward('write'),
+  'git.commit': forward('write'),
+  'git.push': forward('write'),
+  'git.pull': forward('write'),
+  'git.checkout': forward('write'),
+  'git.discard': forward('write'),
+  'git.revert': forward('write'),
+  'git.cherry-pick': forward('write'),
+  // 提交信息生成：消耗主服务端的模型额度（产品决定：跟随会话，接）。
+  'git.suggest-message': forward('write'),
+  // 模型目录：sessionId 可选（lib/index.js:6573-6602、6614-6626）。
+  'git.commit-model': forward('read'),
+  'git.models': forward('read'),
+
+  // ---- 变更流（lib/index.js:6627-6649）----
+  // 事件对象属于该会话自身的流，不带会话 id —— 不改写。
+  'changes.ops': forward('read'),
+
+  // ---- 子代理 / 工作流 / 团队（lib/index.js:4482-4662、4770-4789）----
+  'subagents.live': {
+    kind: 'read',
+    sessionField: 'rootSessionId',
+    // 响应的 live 映射以会话 id 为键（lib/index.js:4513）。
+    rewrite: (body, ctx) => {
+      if (body === null || typeof body !== 'object' || Array.isArray(body)) return body
+      const live = (body as Record<string, unknown>).live
+      if (live === null || typeof live !== 'object' || Array.isArray(live)) return body
+      const rewritten: Record<string, unknown> = {}
+      for (const [id, view] of Object.entries(live as Record<string, unknown>)) {
+        rewritten[ctx.isVirtual(id) ? id : ctx.virtualize(id)] = view
+      }
+      return { ...(body as Record<string, unknown>), live: rewritten }
+    },
+  },
+  'workflows.list': {
+    kind: 'read',
+    sessionField: 'rootSessionId',
+    // 每行的 originSessionId（4666）与 members[].childId（4686）。
+    rewrite: (body, ctx) => {
+      if (body === null || typeof body !== 'object' || Array.isArray(body)) return body
+      const runs = (body as Record<string, unknown>).runs
+      if (!Array.isArray(runs)) return body
+      return {
+        ...(body as Record<string, unknown>),
+        runs: runs.map((run) => rewriteWorkflowRun(run, ctx)),
+      }
+    },
+  },
+  // 响应是 {ok, value:<任务记录>}，不带会话 id —— 不改写。
+  'teams.taskCreate': forward('write', 'rootSessionId'),
+  'teams.taskUpdate': forward('write', 'rootSessionId'),
+
+  // ---- 归档（lib/index.js:6663-6686；响应不带会话 id）----
+  'archive.build': forward('write'),
+  'archive.status': forward('read'),
+
+  // ---- 设置（lib/index.js:6666-6682）----
+  // 无会话字段：定位结果为空，远程判定天然放行本机 —— 表里登记只为
+  // 文档完整与「未知方法」比对（真实存在，只是不转发）。
+  'settings.get': { kind: 'read', local: true },
+  'settings.update': { kind: 'write', local: true },
+
+  // ---- 外部打开（lib/index.js:6683-6687）----
+  // 在宿主机起进程：远程会话拒绝（适配器路由的 deny 钩子按「浏览器当前
+  // 会话是虚拟 id」拒绝；这里登记是让方法比对认识它）。请求体不带会话
+  // 字段（client.js:9383-9392 只发 action/path/url）。
+  'open.external': { kind: 'write', sessionField: 'sessionId' },
+
+  // ---- 侧聊（lib/index.js:4971-5140，buildSidechatApi）----
+  // PB-13 起转发：sidechat 的子会话带 `meta.parentSession = 调用会话 id`
+  // （lib/index.js:5012），zen-remote 的共享按祖先链判定，所以侧聊线程
+  // 自动继承父会话的共享——闭环是 start 的响应 childId 换成虚拟 id，
+  // 浏览器拿它发后续调用时经体定位回本适配器，服务端按继承校验放行。
+  'sidechat.start': {
+    kind: 'write',
+    sessionField: 'sessionId',
+    // 响应 `{ childId }`（lib/index.js:5050）——服务端真实 id 换虚拟。
+    rewrite: (body, ctx) => rewriteTopLevel(body, 'childId', ctx),
+  },
+  'sidechat.prompt': forward('write', 'childId'),
+  'sidechat.cancel': forward('write', 'childId'),
+  'sidechat.dispose': forward('write', 'childId'),
+  'sidechat.info': forward('read', 'childId'),
+  'sidechat.events': forward('read', 'childId'),
+}
+
+/** `/sidebar/api` 的路径前缀（方法名跟在后面，lib/index.js:6888）。 */
+export const SIDEBAR_API_PREFIX = '/sidebar/api/'
+
+/** 从请求 pathname 取出 API 方法名（`/sidebar/api/fs.tree` → `fs.tree`）。 */
+export function sidebarMethodNameOf(pathname: string): string | undefined {
+  if (!pathname.startsWith(SIDEBAR_API_PREFIX)) return undefined
+  const name = pathname.slice(SIDEBAR_API_PREFIX.length)
+  if (name === '' || name.includes('/')) return undefined
+  return name
+}
+
+/** 顶层字段的虚拟化改写（session.cwd 的形状）。 */
+function rewriteTopLevel(body: unknown, field: string, ctx: SidebarRewriteContext): unknown {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) return body
+  const record = body as Record<string, unknown>
+  const value = record[field]
+  if (typeof value !== 'string' || value === '' || ctx.isVirtual(value)) return body
+  return { ...record, [field]: ctx.virtualize(value) }
+}
+
+/** 一行工作流运行的改写（originSessionId + phases[].members[].childId）。 */
+function rewriteWorkflowRun(run: unknown, ctx: SidebarRewriteContext): unknown {
+  if (run === null || typeof run !== 'object' || Array.isArray(run)) return run
+  const record = run as Record<string, unknown>
+  const rewritten: Record<string, unknown> = { ...record }
+  const origin = record.originSessionId
+  if (typeof origin === 'string' && origin !== '' && !ctx.isVirtual(origin)) rewritten.originSessionId = ctx.virtualize(origin)
+  if (Array.isArray(record.phases)) {
+    rewritten.phases = record.phases.map((phase) => {
+      if (phase === null || typeof phase !== 'object' || Array.isArray(phase)) return phase
+      const phaseRecord = phase as Record<string, unknown>
+      if (!Array.isArray(phaseRecord.members)) return phase
+      return {
+        ...phaseRecord,
+        members: phaseRecord.members.map((member) => {
+          if (member === null || typeof member !== 'object' || Array.isArray(member)) return member
+          const memberRecord = member as Record<string, unknown>
+          const childId = memberRecord.childId
+          if (typeof childId !== 'string' || childId === '' || ctx.isVirtual(childId)) return member
+          return { ...memberRecord, childId: ctx.virtualize(childId) }
+        }),
+      }
+    })
+  }
+  return rewritten
+}

package/src/adapters/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The adapter registry — the ONE door between `src/adapters/` and the rest
+ * of the plugin. Every adapter implementation lives in its own
+ * subdirectory (`src/adapters/<plugin-name>/`), is imported here, and adds
+ * exactly one element to the array. Nothing outside `src/index.ts` (the
+ * wiring) may import from this directory, and no file anywhere may import
+ * an adapter subdirectory — both pinned by test/adapters-pluggable.test.cjs.
+ * Deleting this whole directory leaves the plugin fully working: the wiring
+ * parameter defaults to `[]`.
+ *
+ * PB-11 ships the FRAMEWORK only: the array stays EMPTY, the first real
+ * adapter (better-sidebar) arrives with PB-12.
+ */
+
+import type { BridgeAdapter } from './types.js'
+import { dshBetterSidebarAdapter } from './dsh-better-sidebar/index.js'
+
+/** Every adapter zen-remote ships, in registration order. */
+export const ADAPTERS: readonly BridgeAdapter[] = [dshBetterSidebarAdapter]

package/src/adapters/types.ts

@@ -0,0 +1,44 @@
+/**
+ * The adapter-author face of the plugin bridge's adapter framework
+ * (PB-11). An adapter is zen-remote-internal code for ONE third-party
+ * plugin at its EXACT version: it declares which of that plugin's routes
+ * carry a session id and WHERE, and — optionally — hooks the two ends to
+ * refuse, strip or rewrite what the pure id relocation cannot express.
+ * Everything here sits on the framework shapes from
+ * `../plugin-adapter-core.js`; the framework itself never imports this
+ * file (only `src/index.ts` imports the ADAPTERS array from
+ * `./adapters/index.js`), which is what makes the whole directory
+ * removable without touching any other feature.
+ *
+ * An adapter implementation may import `types.ts` and pure utilities such
+ * as `../virtual-id.js` — nothing else.
+ */
+
+import type { AdapterRoute, AdapterRequestContext, AdapterResponseContext, AdapterVerdict } from '../plugin-adapter-core.js'
+
+export type { AdapterRoute, AdapterRequestContext, AdapterResponseContext, AdapterVerdict }
+
+/** One pluggable adapter. `versions` lists the EXACT plugin versions this
+ * adapter was written against — the installed version must be among them
+ * or the adapter does not register at all (a best-guess rewrite against a
+ * moving schema is how ids get corrupted). A plugin that registers its OWN
+ * cooperative declaration always wins; the adapter yields. */
+export interface BridgeAdapter {
+  /** The target plugin's npm package name. */
+  plugin: string
+  /** The checked exact versions; an installed version outside this list
+   * means "not adapted". */
+  versions: readonly string[]
+  routes: readonly AdapterRoute[]
+  /** The sub-client half: rewrite or refuse on the way OUT to the relay,
+   * and map the answer's real session ids back to virtual form. */
+  client?: {
+    request?(ctx: AdapterRequestContext): AdapterVerdict
+    response?(ctx: AdapterResponseContext): unknown
+  }
+  /** The main-server half: refuse or strip (e.g. a `cwd` field) before
+   * the loopback reaches the plugin. */
+  server?: {
+    request?(ctx: AdapterRequestContext): AdapterVerdict
+  }
+}

package/src/admin-routes.ts

@@ -41,6 +41,7 @@ import { request as httpRequest } from 'node:http'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ConfigSource, ZenRemoteConfig } from './config.js'
 import { responseJson, sameOriginPost } from './http.js'
+import type { BridgeRegistry } from './plugin-bridge.js'
 import type { RelayGateway } from './relay-server.js'
 import { restoreBusy } from './share-ops.js'
 import type { AgentStatusLike } from './share-ops.js'
@@ -66,6 +67,10 @@ export const ADMIN_PUSH_TEST_ROUTE = `${ADMIN_ROUTE_PREFIX}/push-test`
  * POST `{action, sessionId?}`: share / unshare / unshare-all (T33a). */
 export const ADMIN_SHARES_ROUTE = `${ADMIN_ROUTE_PREFIX}/shares`
 
+/** GET: the plugin bridge's registered plugins with their whole-machine-data
+ * consent, for the settings page's 插件桥 section (PB-5). */
+export const ADMIN_PLUGIN_BRIDGE_ROUTE = `${ADMIN_ROUTE_PREFIX}/plugin-bridge`
+
 /** Longest wait for one gateway round-trip. */
 const GATEWAY_TIMEOUT_MS = 5000
 
@@ -161,6 +166,18 @@ export interface AdminHandlerOptions {
    * durable header through it to judge subagent sessions; absent (or a
    * failing read) falls back to the projection identity. */
   sessionQuery?: () => SessionQueryLike | undefined
+  /** The plugin bridge's server half (PB-5): the declaration registry and
+   * the LIVE consent reader backing the plugin-bridge listing. Absent — a
+   * composition that never built the registry — and the route answers 404
+   * like any unknown admin path. */
+  pluginBridge?: {
+    registry: BridgeRegistry
+    getConsent: () => Record<string, boolean>
+    /** The plugins an ADAPTER currently stands in for (PB-11), read live
+     * per listing — a plugin that registered its own declaration stops
+     * being marked. Absent on a wiring that predates adapters. */
+    adaptedPlugins?: () => ReadonlySet<string>
+  }
 }
 
 /** The slice of the sessionQuery service the share action reads (RT
@@ -574,6 +591,53 @@ export function createAdminHandler(options: AdminHandlerOptions): AdminHandler {
         responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use GET or POST' } })
         return
       }
+      if (route === ADMIN_PLUGIN_BRIDGE_ROUTE) {
+        // No registry, no route: a composition that never built the plugin
+        // bridge answers like any unknown admin path.
+        if (options.pluginBridge === undefined) {
+          responseJson(res, 404, { ok: false, error: { code: 'not-found', message: 'Unknown admin route' } })
+          return
+        }
+        if (method !== 'GET') {
+          res.setHeader('Allow', 'GET')
+          responseJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'Use GET' } })
+          return
+        }
+        // Wall 2, the pair/action rule: this listing feeds a MANAGEMENT
+        // surface (the consent toggles below it), so a request that arrived
+        // through the gateway is refused — consent is granted on the server
+        // machine, by its owner, period.
+        if (req.headers['x-zen-remote-via'] !== undefined) {
+          responseJson(res, 403, {
+            ok: false,
+            error: { code: 'via-gateway', message: '插件桥设置只能在服务端本机操作' },
+          })
+          return
+        }
+        // The consent source is a live row read; a broken one reads as the
+        // empty map (nothing consented) instead of failing the listing.
+        let consent: Record<string, boolean> = {}
+        try {
+          consent = options.pluginBridge.getConsent()
+        } catch {
+          consent = {}
+        }
+        // registry.list() arrives plugin-sorted; the map keeps that order.
+        // PB-11: `adapted` marks the entries an ADAPTER stands in for —
+        // zen-remote-internal forwarding for a plugin that never registered
+        // anything — so the settings page can say「由 zen-remote 适配」.
+        // Absent (a wiring that predates adapters) reads as none.
+        const adapted = options.pluginBridge.adaptedPlugins?.() ?? new Set<string>()
+        const plugins = options.pluginBridge.registry.list().map((declaration) => ({
+          plugin: declaration.plugin,
+          version: declaration.version,
+          hasServerScope: declaration.routes.some((route) => route.scope === 'server'),
+          consent: consent[declaration.plugin] === true,
+          adapted: adapted.has(declaration.plugin),
+        }))
+        responseJson(res, 200, { ok: true, value: { plugins } })
+        return
+      }
       if (route === ADMIN_PAIR_ROUTE || route === ADMIN_ACTION_ROUTE || route === ADMIN_PUSH_TEST_ROUTE) {
         if (method !== 'POST') {
           res.setHeader('Allow', 'POST')

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

@@ -2,6 +2,8 @@ import type { ClientContext, MobileSessionRow } from '../compat/types.ts'
 import { mainSessionIdOf } from '../compat/types.ts'
 import { isVirtual } from '../../virtual-id.ts'
 import { REMOTE_SESSION_CSS } from '../styles/remote-session.css.ts'
+import { BRIDGE_STAMP_ATTRIBUTE, BRIDGE_STAMP_PLUGIN, getRemoteStatusStore, shouldStampBridgeAttribute, subscribeIfVirtual } from '../../client-data/remote-status.ts'
+import { en, zh } from '../locales.ts'
 
 /**
  * The remote-session marker (T41b): the CURRENT main-view session id, read
@@ -25,6 +27,29 @@ import { REMOTE_SESSION_CSS } from '../styles/remote-session.css.ts'
  * attribute must track the current session regardless of which panel is
  * mounted, and an attribute + stylesheet survives every re-render untouched.
  */
+
+/** The CURRENT main-view session id, the publishMain way (see the module
+ * comment). Shared by the session marker and the bridge stamp — both key on
+ * the same "which session is on screen" answer. */
+function currentMainSessionIdOf(ctx: ClientContext): string | undefined {
+  const { byId } = ctx.sessions.list.getSnapshot()
+  const uiSession = ctx.get('uiSession') as { current?: { value?: { key?: unknown } } } | undefined
+  const current = uiSession?.current?.value?.key
+  const rows = byId as Readonly<Record<string, MobileSessionRow>>
+  return typeof current === 'string' && (rows[current]?.retainedBy?.mainView ?? 0) > 0
+    ? current
+    : mainSessionIdOf(byId)
+}
+
+/** The unbridged note copy in the BROWSER's language (the plugin's own
+ * namespace carries both dictionaries; the framework `t` seat is not
+ * reachable from a non-React effect, so the navigator's language picks —
+ * `zh*` reads Chinese, everything else English). */
+function bridgeNoteOf(language: string | undefined): string {
+  const key = 'remoteBridgeUnbridgedNote' as const
+  return typeof language === 'string' && language.startsWith('zh') ? zh[key] : en[key]
+}
+
 export function installRemoteSessionGuard(ctx: ClientContext): void {
   ctx.effect(() => {
     const tag = document.createElement('style')
@@ -39,16 +64,7 @@ export function installRemoteSessionGuard(ctx: ClientContext): void {
 
   ctx.effect(() => {
     const apply = (): void => {
-      const { byId } = ctx.sessions.list.getSnapshot()
-      // publishMain's tie-break (see the module comment): prefer the still-
-      // retained current main binding, else the first mainView row.
-      const uiSession = ctx.get('uiSession') as { current?: { value?: { key?: unknown }, subscribe?: (listener: () => void) => () => void } } | undefined
-      const current = uiSession?.current?.value?.key
-      const rows = byId as Readonly<Record<string, MobileSessionRow>>
-      const sessionId =
-        typeof current === 'string' && (rows[current]?.retainedBy?.mainView ?? 0) > 0
-          ? current
-          : mainSessionIdOf(byId)
+      const sessionId = currentMainSessionIdOf(ctx)
       const root = document.documentElement
       if (sessionId !== undefined && isVirtual(sessionId)) root.setAttribute('data-zr-remote-session', '1')
       else root.removeAttribute('data-zr-remote-session')
@@ -65,4 +81,60 @@ export function installRemoteSessionGuard(ctx: ClientContext): void {
       document.documentElement.removeAttribute('data-zr-remote-session')
     }
   }, 'dsh-zen-remote: remote-session attribute')
+
+  // The bridge stamp (PB-14): while a REMOTE session is on screen, the
+  // remote-status poll's `bridgedPlugins` decides whether better-sidebar is
+  // bridged RIGHT NOW — bridged, the T53 hiding rules lift (the panels read
+  // the server's data through the adapter) and the html carries
+  // `data-zr-bridge-dsh-better-sidebar="1"`; not bridged, the rules stay
+  // and the html carries the unbridged note copy as a CSS variable the
+  // stylesheet spends on the empty tab body. The subscription rides
+  // subscribeIfVirtual — a LOCAL session (or a host page) never polls, and
+  // the attribute comes off; better-sidebar not installed or the server not
+  // paired simply never appear in `bridgedPlugins`, so the stamp never
+  // fires from this side alone.
+  ctx.effect(() => {
+    const root = document.documentElement
+    const store = getRemoteStatusStore()
+    let offStore: (() => void) | undefined
+    const clear = (): void => {
+      root.removeAttribute(BRIDGE_STAMP_ATTRIBUTE)
+      root.style.removeProperty('--zr-bridge-note')
+    }
+    const applyBridge = (): void => {
+      const view = store.getSnapshot().view
+      if (shouldStampBridgeAttribute(view?.bridgedPlugins, BRIDGE_STAMP_PLUGIN)) {
+        root.setAttribute(BRIDGE_STAMP_ATTRIBUTE, '1')
+        root.style.removeProperty('--zr-bridge-note')
+      } else {
+        root.removeAttribute(BRIDGE_STAMP_ATTRIBUTE)
+        // JSON.stringify's quotes are a legal CSS string — the stylesheet's
+        // ::before spends it as `content: var(--zr-bridge-note)`.
+        root.style.setProperty('--zr-bridge-note', JSON.stringify(bridgeNoteOf(navigator.language)))
+      }
+    }
+    const retune = (): void => {
+      const sessionId = currentMainSessionIdOf(ctx)
+      const virtualNow = sessionId !== undefined && isVirtual(sessionId)
+      if (virtualNow && offStore === undefined && typeof sessionId === 'string') {
+        offStore = subscribeIfVirtual(store, sessionId, applyBridge)
+        applyBridge()
+        return
+      }
+      if (!virtualNow && offStore !== undefined) {
+        offStore()
+        offStore = undefined
+        clear()
+      }
+    }
+    retune()
+    const offs: Array<() => void> = [ctx.sessions.list.subscribe(retune)]
+    const current = (ctx.get('uiSession') as { current?: { subscribe?: (listener: () => void) => () => void } } | undefined)?.current
+    if (typeof current?.subscribe === 'function') offs.push(current.subscribe(retune))
+    return () => {
+      for (const off of offs) off()
+      offStore?.()
+      clear()
+    }
+  }, 'dsh-zen-remote: bridge stamp')
 }