dsh-zen-remote 2.3.3 → 2.3.4

package/lib/upload-limits.js

@@ -0,0 +1,67 @@
+/**
+ * The one home of every upload/body ceiling this plugin enforces (the
+ * upload unification, 2026-10-28). Three paths move bytes through the
+ * plugin, each with its own number, and the numbers used to live beside
+ * their enforcement sites — where they drifted: the docs still said
+ * 100 MiB, the nginx snippet capped at 128m under a 500 MiB relay, and
+ * the better-sidebar adapter hand-copied the relay budget (kept in step
+ * only by a paired test). Defining them here once makes each number
+ * greppable to exactly one place; scripts/check-upload-limits.mjs pins
+ * the rest — no second MiB-scale constant definition anywhere in src/,
+ * and the docs / nginx snippet stay in sync with MAX_UPLOAD_BYTES.
+ *
+ * Pure constants, ZERO imports (the virtual-id.ts precedent): the relay
+ * server, the phone-upload route, the sub-client's fetch-route intercept,
+ * the adapter core and the adapters themselves all import from here — an
+ * adapter may only lean on pure utility modules, so anything less pure
+ * would have kept the hand-copies alive.
+ */
+/**
+ * Body ceiling for the binary upload channel alone (T51): a shared session's
+ * non-image file attachments. DSH's own upload route has NO byte cap — the
+ * host stores the stream verbatim (`saveFileStreamVerbatim` →
+ * `publishImmutableObjectStream`, RT dsh-attachment-local lib/index.js
+ * ~699-716; the 20 MiB `maxImageBytes` there covers INLINE images only), so
+ * there is no host number to mirror and this relay picks its own: 500 MiB
+ * per upload, checked first against `Content-Length` (refused before a byte
+ * moves) and then counted while the stream is pumped (a chunked body has no
+ * length header — the sub-client's undici forbids hand-set length headers,
+ * so the streaming count is the path its uploads normally take). Past the
+ * cap the forward is aborted, the rest of the request is drained and the
+ * answer is 413 `payload-too-large`.
+ *
+ * SLOW-LINK BOUND (T51-fix, for the docs): a single legitimate upload is
+ * also bounded in TIME. The sub-client's own round-trip budget now caps at
+ * 15 minutes (relay-client.ts, the T31-fix rule), but the HOST's HTTP server
+ * keeps Node's default 300 s request deadline — that is the binding limit:
+ * a 500 MiB body needs roughly 14 Mbps sustained end to end, and a slower
+ * link fails the call (the client-side refusal keeps the connection state)
+ * rather than hanging. Raising the cap past what that deadline can carry
+ * would only move the failure, so 500 MiB is the honest ceiling for the
+ * current transport.
+ */
+export const MAX_UPLOAD_BYTES = 500 * 1024 * 1024;
+/**
+ * Body cap when the plugin row sets no `maxUploadBytes`. This governs ONLY
+ * the phone composer's attachment upload (`/_dsh/mobile-nav/upload`) — the
+ * remote relay channel reads {@link MAX_UPLOAD_BYTES} and must never be
+ * sized from this: `maxUploadBytes` is a user-facing knob for phone picks
+ * (default 20 MB), and wiring it into the relay would drop remote
+ * attachments from 500 MiB back down to it (a regression the README's
+ * 500 MiB promise forbids).
+ */
+export const DEFAULT_MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+/**
+ * Body ceiling for the relay's invoke route alone: the prompt routes carry
+ * inline images in their content blocks (`session/prompt` / `subagents/prompt`
+ * take base64 `image` parts; DSH admits one image up to 20 MiB by default —
+ * `maxImageBytes`, dsh-attachment-local — which base64 inflates to ~27 MiB),
+ * so one full-size inline image plus its envelope needs 32 MiB. It is NOT
+ * sized for `fileUploads/upload`: the UI's real file uploads ride the HTTP
+ * route `api/session/uploadFileBinary` (T41b), not this JSON relay. The
+ * buffer only ever grows to the REAL body size; the cap decides
+ * accept/refuse, and a body that outgrows it is drained and answered 413
+ * like any other oversized read.
+ */
+export const MAX_INVOKE_BODY_BYTES = 32 * 1024 * 1024;
+//# sourceMappingURL=upload-limits.js.map

package/lib/upload-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-limits.js","sourceRoot":"","sources":["../src/upload-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAEjD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAA"}

package/lib/wizard/proxy-snippets.js

@@ -32,9 +32,10 @@ function validatedParts(input) {
  * nginx: a complete server block. The WebSocket upgrade map sits outside
  * the server (http-level context) — the snippet says so in a comment, the
  * user pastes it into the http/server scope their setup offers. Long
- * idle tunnels need the 3600s read/send timeouts, uploads the 128m
- * client body cap, and streaming the buffering switch — all three are
- * the shapes DSH's relay traffic actually needs.
+ * idle tunnels need the 3600s read/send timeouts, uploads the 512m
+ * client body cap (nginx's `m` is MiB — 512m covers the relay's 500 MiB
+ * upload ceiling with headroom), and streaming the buffering switch — all
+ * three are the shapes DSH's relay traffic actually needs.
  */
 export function nginxSnippet(input) {
     const parts = validatedParts(input);
@@ -62,7 +63,7 @@ export function nginxSnippet(input) {
         '        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;',
         '        proxy_set_header X-Forwarded-Proto $scheme;',
         '        proxy_buffering off;',
-        '        client_max_body_size 128m;',
+        '        client_max_body_size 512m;',
         '        proxy_read_timeout 3600s;',
         '        proxy_send_timeout 3600s;',
         '    }',

package/lib/wizard/proxy-snippets.js.map

@@ -1 +1 @@
-{"version":3,"file":"proxy-snippets.js","sourceRoot":"","sources":["../../src/wizard/proxy-snippets.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"proxy-snippets.js","sourceRoot":"","sources":["../../src/wizard/proxy-snippets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAgBrC,mCAAmC;AACnC,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACjH,CAAC;AAED,SAAS,cAAc,CAAC,KAAmB;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACnC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,CAAA;IAC9E,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IAC3C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,CAAA;IACvF,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IACvC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,CAAA;IACnF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;AACnC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,KAAmB;IAC9C,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IACnC,IAAI,OAAO,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,KAAK,CAAA;IACxC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IACxC,MAAM,IAAI,GAAG;QACX,iCAAiC;QACjC,yCAAyC;QACzC,sBAAsB;QACtB,oBAAoB;QACpB,GAAG;QACH,EAAE;QACF,UAAU;QACV,qBAAqB;QACrB,mBAAmB,MAAM,GAAG;QAC5B,EAAE;QACF,kBAAkB;QAClB,6BAA6B,QAAQ,IAAI,IAAI,GAAG;QAChD,iCAAiC;QACjC,iDAAiD;QACjD,0DAA0D;QAC1D,sCAAsC;QACtC,kDAAkD;QAClD,sEAAsE;QACtE,qDAAqD;QACrD,8BAA8B;QAC9B,oCAAoC;QACpC,mCAAmC;QACnC,mCAAmC;QACnC,OAAO;QACP,GAAG;QACH,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACZ,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAmB;IAC9C,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAA;IACnC,IAAI,OAAO,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,KAAK,CAAA;IACxC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IACxC,MAAM,IAAI,GAAG;QACX,GAAG,MAAM,IAAI;QACb,qBAAqB,QAAQ,IAAI,IAAI,EAAE;QACvC,GAAG;QACH,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACZ,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AAC3B,CAAC;AAMD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAuD;IAChF,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IAC3C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAA;IAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IACvC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAA;IACxE,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE;YACL,4CAA4C;YAC5C,oBAAoB,QAAQ,IAAI,IAAI,mBAAmB;YACvD,4BAA4B;SAC7B;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-zen-remote",
-  "version": "2.3.3",
+  "version": "2.3.4",
   "description": "一个插件、两种角色：主服务端把 DeepSeek Harness 变成手机能安全访问的 PWA（移动端界面、配对码网关、Web Push），并把选定会话共享给已配对的桌面端；子客户端在另一台 DSH 桌面端的侧边栏里远程使用这些会话。One DSH plugin, two roles: the host turns DeepSeek Harness into a phone-reachable PWA (mobile UI, pairing-code gateway behind your own reverse proxy, Web Push) and shares chosen sessions to paired desktops; the client uses those sessions remotely from another DSH desktop app's sidebar.",
   "license": "MIT",
   "type": "module",
@@ -160,7 +160,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/build-client.mjs",
     "verify": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
-    "test": "node --test \"test/*.test.cjs\" && node scripts/check-sunk-viewport.mjs && node scripts/check-keyboard-avoid.mjs && node scripts/check-attach-upload.mjs && node scripts/check-share-image.mjs && node scripts/check-upload-endpoint.mjs && node scripts/check-host-shadow.mjs && node scripts/check-compat-store.mjs && node scripts/check-settings-form.mjs && node scripts/check-shares.mjs && node scripts/check-plugin-bridge-ui.mjs && node scripts/check-remote-drop.mjs && node scripts/check-client-externals.mjs && node scripts/check-info-sheet-stacking.mjs && node scripts/check-wizard-ui.mjs && node scripts/sync-doc-version.mjs --check",
+    "test": "node --test \"test/*.test.cjs\" && node scripts/check-sunk-viewport.mjs && node scripts/check-keyboard-avoid.mjs && node scripts/check-attach-upload.mjs && node scripts/check-share-image.mjs && node scripts/check-upload-endpoint.mjs && node scripts/check-host-shadow.mjs && node scripts/check-compat-store.mjs && node scripts/check-settings-form.mjs && node scripts/check-shares.mjs && node scripts/check-plugin-bridge-ui.mjs && node scripts/check-remote-drop.mjs && node scripts/check-client-externals.mjs && node scripts/check-info-sheet-stacking.mjs && node scripts/check-wizard-ui.mjs && node scripts/check-upload-limits.mjs && node scripts/sync-doc-version.mjs --check",
     "version": "node scripts/sync-doc-version.mjs && git add README.md README.zh-CN.md"
   }
 }

package/scripts/check-upload-limits.mjs

@@ -0,0 +1,167 @@
+/**
+ * The upload-limits drift check (the upload unification, 2026-10-28).
+ * The plugin's upload ceilings live in exactly one place —
+ * src/upload-limits.ts — and this script keeps the rest of the repo in
+ * step with it, the way sync-doc-version.mjs keeps the READMEs in step
+ * with package.json: every target below is REQUIRED, and a missing
+ * marker exits non-zero rather than quietly passing, because a silent
+ * no-op is exactly the failure each pin exists to prevent.
+ *
+ *  a. Both languages' docs state the `/v1/upload` route's cap, and every
+ *     MiB number on that table row equals MAX_UPLOAD_BYTES (the docs
+ *     drifted to "100 MiB" once already).
+ *  b. Every nginx `client_max_body_size <N>m;` the repo hands out — the
+ *     wizard's generated snippet and the docs' example block — is at
+ *     least MAX_UPLOAD_BYTES in MiB (nginx's `m` is MiB; the snippet sat
+ *     at 128m under a 500 MiB relay once already). The Chinese doc must
+ *     carry the example; the English doc is checked wherever it appears.
+ *  c. A static scan: no upload-limit VALUE may reappear as a constant
+ *     definition anywhere else in the repo (the better-sidebar adapter
+ *     hand-copied the relay budget once already, kept honest only by a
+ *     paired test). The scan matches `const X = <N> * 1024 * 1024`
+ *     definitions for the three shipped values, so unrelated MiB
+ *     constants (the 64 MiB bridge body cap, the 512 MiB download cap,
+ *     buffer sizes) stay untouched — and so do test-side literal
+ *     arguments, which are assertions, not definitions.
+ *
+ * Imports the BUILT lib/upload-limits.js — run after `pnpm build` (the
+ * test script already is). The scan reads the values at run time, so
+ * raising a limit in upload-limits.ts moves every pin with it.
+ */
+
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const limits = await import(pathToFileURL(join(root, 'lib', 'upload-limits.js')).href)
+const capMib = limits.MAX_UPLOAD_BYTES / (1024 * 1024)
+
+const failures = []
+
+// --- a. the docs' `/v1/upload` row states the relay cap ---------------------
+
+const DOCS = ['docs/remote-access.md', 'docs/remote-access.en.md']
+
+for (const file of DOCS) {
+  const row = readFileSync(join(root, file), 'utf8')
+    .split('\n')
+    .find((line) => /^\|\s*`\/v1\/upload`\s*\|/.test(line))
+  if (row === undefined) {
+    failures.push(`${file}: no \`/v1/upload\` table row found — the docs moved, update this check`)
+    continue
+  }
+  const mibs = [...row.matchAll(/(\d+(?:\.\d+)?)\s*MiB/g)].map((match) => Number(match[1]))
+  if (mibs.length === 0) {
+    failures.push(`${file}: the \`/v1/upload\` row states no MiB cap — the docs moved, update this check`)
+    continue
+  }
+  for (const mib of mibs) {
+    if (mib !== capMib) failures.push(`${file}: the \`/v1/upload\` row says ${mib} MiB but MAX_UPLOAD_BYTES is ${capMib} MiB`)
+  }
+}
+
+// --- a2. the READMEs' marketing claim ("up to 500 MiB file uploads") rides the
+// same number (no `/v1/upload` table there — the mention just has to exist
+// and match, so raising the cap drags the READMEs along) ---------------------
+
+const READMES = ['README.md', 'README.zh-CN.md']
+
+for (const file of READMES) {
+  const text = readFileSync(join(root, file), 'utf8')
+  const mibs = [...text.matchAll(/(\d+)\s*MiB/g)].map((match) => Number(match[1]))
+  if (!mibs.includes(capMib)) {
+    failures.push(`${file}: no "${capMib} MiB" mention found — the upload-cap claim drifted from MAX_UPLOAD_BYTES`)
+  }
+  for (const mib of new Set(mibs)) {
+    if (mib !== capMib && mib > 100) failures.push(`${file}: mentions ${mib} MiB — a stale upload-cap claim? (only ${capMib} is the relay number)`)
+  }
+}
+
+// --- b. every nginx body cap we hand out covers the relay -------------------
+
+const NGINX_CAP = /client_max_body_size\s+(\d+)m\s*;/g
+
+const nginxCapsOf = (text) => [...text.matchAll(NGINX_CAP)].map((match) => Number(match[1]))
+
+const { nginxSnippet } = await import(pathToFileURL(join(root, 'lib', 'wizard', 'proxy-snippets.js')).href)
+const snippet = nginxSnippet({ domain: 'dsh.example.com', upstreamHost: '127.0.0.1', upstreamPort: 4088 })
+if (!snippet.ok) {
+  failures.push('wizard nginxSnippet refused a plainly valid input — the generator broke')
+} else {
+  const caps = nginxCapsOf(snippet.text)
+  if (caps.length === 0) {
+    failures.push('wizard nginx snippet: no `client_max_body_size` found — the snippet moved, update this check')
+  }
+  for (const cap of caps) {
+    if (cap < capMib) failures.push(`wizard nginx snippet: client_max_body_size ${cap}m is below the relay cap (${capMib}m)`)
+  }
+}
+
+for (const file of DOCS) {
+  const caps = nginxCapsOf(readFileSync(join(root, file), 'utf8'))
+  if (file === 'docs/remote-access.md' && caps.length === 0) {
+    failures.push(`${file}: no nginx \`client_max_body_size\` example found — the docs moved, update this check`)
+  }
+  for (const cap of caps) {
+    if (cap < capMib) failures.push(`${file}: client_max_body_size ${cap}m is below the relay cap (${capMib}m)`)
+  }
+}
+
+// --- c. the one-definition scan ----------------------------------------------
+
+/** The value each upload-limit constant ships, by name — the scan keys on
+ * the VALUES so raising a limit in upload-limits.ts moves the pin too. */
+const LIMIT_VALUES = Object.entries({
+  MAX_UPLOAD_BYTES: limits.MAX_UPLOAD_BYTES,
+  DEFAULT_MAX_UPLOAD_BYTES: limits.DEFAULT_MAX_UPLOAD_BYTES,
+  MAX_INVOKE_BODY_BYTES: limits.MAX_INVOKE_BODY_BYTES,
+})
+
+const GUARDED = 'src/upload-limits.ts'
+const SKIP_DIRS = new Set(['node_modules', 'lib', 'dist'])
+const SCAN_EXT = /\.(ts|mts|cts|js|mjs|cjs)$/
+
+const files = []
+const walk = (dir) => {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) walk(full)
+    } else if (SCAN_EXT.test(entry.name)) {
+      files.push(full)
+    }
+  }
+}
+walk(join(root, 'src'))
+walk(join(root, 'test'))
+walk(join(root, 'scripts'))
+walk(join(root, 'pwa'))
+for (const entry of readdirSync(root, { withFileTypes: true })) {
+  if (entry.isFile() && SCAN_EXT.test(entry.name)) files.push(join(root, entry.name))
+}
+
+for (const full of files) {
+  const rel = relative(root, full).split('\\').join('/')
+  if (rel === GUARDED) continue
+  const text = readFileSync(full, 'utf8')
+  for (const [name, bytes] of LIMIT_VALUES) {
+    const mib = bytes / (1024 * 1024)
+    const defines = new RegExp(
+      `\\b(?:const|let|var)\\s+[A-Za-z_$][\\w$]*\\s*(?::[^=\\n]+)?=\\s*${mib}\\s*\\*\\s*1024\\s*\\*\\s*1024\\b`,
+    )
+    if (defines.test(text)) {
+      failures.push(`${rel}: defines a ${mib} MiB upload-limit literal — import ${name} from src/upload-limits.ts instead`)
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+
+if (failures.length > 0) {
+  console.error(`check-upload-limits: drift against src/upload-limits.ts:\n  ${failures.join('\n  ')}`)
+  process.exit(1)
+}
+console.log(
+  `check-upload-limits: docs state ${capMib} MiB, nginx covers it, one definition (src/upload-limits.ts) — ok`,
+)

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

@@ -31,15 +31,9 @@
 
 import type { BridgeAdapter } from '../types.js'
 import { isVirtual } from '../../virtual-id.js'
+import { MAX_UPLOAD_BYTES } from '../../upload-limits.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 = 500 * 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. */
@@ -74,6 +68,24 @@ export const dshBetterSidebarAdapter: BridgeAdapter = {
   // and only then a client `cwd` hint — so the server hook's cwd stripping
   // below stays correct (if anything, the client hint matters less).
   versions: ['0.25.0', '0.26.0', '0.26.1', '0.28.0-alpha.0', '0.28.0', '0.28.1', '0.28.2'],
+  // PB-19 (ADR-0003): the wire-surface whitelist. Keys are digest16 over the
+  // PB-18 extractor's reduction (`surface.ts` beside this file) of the npm
+  // builds' lib/index.js, computed off /tmp/bs-versions/{version}/lib/index.js:
+  //   d383e5af5b95e456 — the 0.25.0 generation
+  //   96465143373a31a7 — the 0.26.0 generation (0.26.1 hashes identically)
+  //   6ed29a896101e681 — the 0.28.0 generation (0.28.0-alpha.0 identically)
+  //   65a0acaeb56f87d9 — the 0.28.1 generation (0.28.2 identically)
+  // An installed version outside `versions` still registers when its build
+  // hashes into one of these (a wire-identical patch release bridges without
+  // a zen-remote release); anything else fails closed to the unlisted-version
+  // refusal — including an upstream edit that touches only a path-mentioning
+  // comment, which the extractor counts. NOT part of the route-table digest.
+  surfaces: {
+    d383e5af5b95e456: 'the 0.25.0 generation',
+    '96465143373a31a7': 'the 0.26.0 generation (0.26.1 identical)',
+    '6ed29a896101e681': 'the 0.28.0 generation (0.28.0-alpha.0 identical)',
+    '65a0acaeb56f87d9': 'the 0.28.1 generation (0.28.2 identical)',
+  },
   routes: [
     {
       // The JSON API: the method name rides the path tail, the session
@@ -110,13 +122,13 @@ export const dshBetterSidebarAdapter: BridgeAdapter = {
     { 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' } },
+    { path: '/sidebar/upload', match: 'exact', methods: ['POST'], maxBody: MAX_UPLOAD_BYTES, locator: { in: 'query', name: 'sessionId' } },
     // The raw text write (0.26.0, lib/index.js:7875-7919): the document IS
     // the POST body (text/plain — no JSON escaping layer), the session id,
     // path and a client cwd ride the QUERY. The plugin caps the body at
     // WRITE_BODY_GUARD_BYTES = 8 MiB (lib/index.js:6854); the adapter takes
     // 10 MiB — headroom over the plugin's own guard, under the relay's
-    // 100 MiB upload budget.
+    // 500 MiB upload budget.
     { path: '/sidebar/write', match: 'exact', methods: ['POST'], maxBody: 10 * 1024 * 1024, 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

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

@@ -0,0 +1,90 @@
+/**
+ * The better-sidebar wire-surface extractor (PB-18, ADR-0003 local draft).
+ *
+ * The adapter's `versions` list pins EXACT upstream versions, so a wire-identical
+ * patch release (0.26.1, 0.28.2 — both shipped with the routes/methods/WebSockets
+ * byte-identical to their predecessor) still refuses to bridge until zen-remote
+ * itself releases. The `surfaces` table (PB-19) closes that gap: the wiring reads
+ * the INSTALLED plugin's `lib/index.js`, this pure function reduces it to the
+ * set of `/sidebar/*` routes and `ns.method` dispatch keys it serves, and a
+ * digest over that reduction whitelists every version whose WIRE SURFACE matches
+ * a blessed one — regardless of the version string.
+ *
+ * What the extraction is NOT: a general static analyzer, nor a pure wire
+ * oracle. It knows better-sidebar's two shapes — the `"x.y": async (…)`
+ * dispatch-table entries inside its bundled lib/index.js (the same recognition
+ * test/adapter-better-sidebar.test.cjs layer 1 has pinned since PB-12), and
+ * every `/sidebar/…` string literal the bundle carries. The npm build KEEPS
+ * comments (0.28.2 ships ~470 `/**` blocks, some quoting path strings), and the
+ * routes set below therefore collects registered routes, prefix checks and
+ * comment mentions alike — the digest is stable exactly as long as ALL those
+ * literals are (PB-18 review, verified with comment add/remove probes). That
+ * is STRICTER than "wire unchanged": an upstream release that only edits a
+ * path-mentioning comment changes the digest and fails closed to the
+ * unlisted-version behavior of today — never an unsafe forward, just a smaller
+ * auto-bridge hit rate than a pure wire comparison would give. A bundler that
+ * stops emitting the literals at all fails the same closed direction.
+ *
+ * Pure by the adapters rule: node:crypto only, no fs, no DSH imports.
+ */
+import { createHash } from 'node:crypto'
+
+/** The recognized wire surface: sorted route paths + sorted dispatch keys. */
+export interface BetterSidebarSurface {
+  routes: string[]
+  methods: string[]
+}
+
+/** The dispatcher namespaces the plugin has used across 0.25.0–0.28.2. The
+ * same object-key regex also matches unrelated tables in the bundle, so only
+ * these prefixes count (the PB-12 test's filter, verbatim). */
+const NAMESPACE_PATTERN = /^(session|fs|git|changes|subagents|workflows|teams|settings|open|archive|sidechat)\./u
+
+/** A healthy build of any supported generation yields at least this many
+ * dispatch keys (0.25.0 already serves 45+). Fewer means the extractor lost
+ * the table — the wiring logs that distinctly from "surface changed". */
+export const MIN_SURFACE_METHODS = 45
+
+/** Every `/sidebar/…` literal in the bundle — registered routes (the upload
+ * prefix, the deeper media route) plus prefix checks and comment mentions.
+ * Lowercase only on purpose: the routes themselves are lowercase, and a
+ * case-insensitive scan would swallow uppercase prose noise for no gain
+ * (PB-18 review nit — the `i` flag is deliberately absent). */
+const ROUTE_PATTERN = /\/sidebar\/[a-z0-9./:-]+/gu
+
+/** `"ns.method":` dispatch-table entries (`async` optional after the colon). */
+const METHOD_PATTERN = /"([a-zA-Z]+\.[a-zA-Z-]+)":\s*(?:async\s*)?\(/gu
+
+/** Reduce one build's lib/index.js source to its surface fingerprint.
+ * Deterministic: same source in, same sorted arrays out — the digest below is
+ * a pure function of the surface. Empirically, wire-identical patch releases
+ * also hash identically (0.26.1's perf work, 0.28.2's cwd fix — both kept
+ * every extracted literal); see the header for why that is a fact about those
+ * releases, not a structural guarantee. */
+export function extractBetterSidebarSurface(source: string): BetterSidebarSurface {
+  const routes = new Set<string>()
+  for (const match of source.matchAll(ROUTE_PATTERN)) {
+    // A literal matched through a sentence like "/sidebar/api/foo." would drag
+    // a sentence-period into the set — trim one trailing dot so prose mentions
+    // normalize to the same literal the code registers.
+    routes.add(match[0].replace(/\.$/u, ''))
+  }
+  const methods = new Set<string>()
+  for (const match of source.matchAll(METHOD_PATTERN)) {
+    if (NAMESPACE_PATTERN.test(match[1])) methods.add(match[1])
+  }
+  return { routes: [...routes].sort(), methods: [...methods].sort() }
+}
+
+/** Whether an extraction looks like a real better-sidebar build at all (the
+ * "extractor found nothing" tell — logged apart from digest mismatches). */
+export function surfaceLooksHealthy(surface: BetterSidebarSurface): boolean {
+  return surface.methods.length >= MIN_SURFACE_METHODS && surface.routes.length > 0
+}
+
+/** The 16-hex digest a `surfaces` table key carries: sha256 over the canonical
+ * JSON of the surface. Same surface across versions → same digest → bridged. */
+export function betterSidebarSurfaceDigest(surface: BetterSidebarSurface): string {
+  const canonical = JSON.stringify({ routes: surface.routes, methods: surface.methods })
+  return createHash('sha256').update(canonical, 'utf8').digest('hex').slice(0, 16)
+}

package/src/adapters/types.ts

@@ -21,15 +21,26 @@ export type { AdapterRoute, AdapterRequestContext, AdapterResponseContext, Adapt
 /** 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. */
+ * moving schema is how ids get corrupted). One exception (PB-19): a version
+ * outside the list still registers when the installed build's WIRE-SURFACE
+ * digest appears in {@link BridgeAdapter.surfaces} — a wire-identical patch
+ * release bridges without a zen-remote release. 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". */
+   * means "not adapted" — unless its wire surface is whitelisted in
+   * {@link BridgeAdapter.surfaces}. */
   versions: readonly string[]
   routes: readonly AdapterRoute[]
+  /** The wire-surface whitelist (PB-19, ADR-0003): digest16 of the
+   * adapter's surface-extractor reduction of the installed `lib/index.js`
+   * (routes + dispatch keys) → a remark naming the generation that produced
+   * it. Consulted ONLY when the installed version misses `versions`; never
+   * part of the route-table digest — this is an admission credential, not a
+   * wire contract. */
+  surfaces?: Readonly<Record<string, string>>
   /** 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?: {

package/src/client-data/wizard.ts

@@ -401,7 +401,7 @@ export function nginxSnippetText(input: SnippetInput): string | null {
     '        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;',
     '        proxy_set_header X-Forwarded-Proto $scheme;',
     '        proxy_buffering off;',
-    '        client_max_body_size 128m;',
+    '        client_max_body_size 512m;',
     '        proxy_read_timeout 3600s;',
     '        proxy_send_timeout 3600s;',
     '    }',