dsh-zen-remote 2.3.3 → 2.3.5

package/src/plugin-route-intercept.ts

@@ -9,9 +9,44 @@
  * cannot be served locally (the session lives on the server): the surrogate
  * handler forwards it through `relay.pluginRequest` (PB-3's
  * `relay/v1/plugin`) with the real id restored, and streams the answer
- * back. Everything else — undeclared routes, local sessions — flows to the
+ * back (PB-21: where the id lives is the route's own declaration — the 2.1
+ * query parameter, or a declaration-v2 locator in a prefix route's path
+ * segment or the JSON body; the v2 shapes ride the SAME adapter-core
+ * locate → classify → rewrite functions the adapters run, and a
+ * `prefix: true` route forwards its full matched, rewritten path).
+ * Everything else — undeclared routes, local sessions — flows to the
  * original route untouched.
  *
+ * PB-22 gives the two remaining declaration-v2 flags their client meaning:
+ * a `deny: true` route answers the uniform 503 with reason `route-denied`
+ * whenever a REMOTE context touches it — the request locating a virtual id,
+ * or the browser's CURRENT session being one (T62's signal) — while a local
+ * session passes through exactly as before; a `rewriteIds: true` route's
+ * JSON answer is buffered (the 8 MB adapter cap) and deep-scanned, every
+ * string EXACTLY equal to one of the request's own real session ids
+ * rewritten to its virtual form (`zr~` carries the real id inside, so the
+ * request's own hits ARE the read-only mapping — no table is consulted or
+ * written), unknown strings passing through untouched.
+ *
+ * PB-25a adds the position form: `rewriteIds: { fields }` declares the dot
+ * paths where the response's NEWLY-CREATED session ids sit (a creation
+ * route's `childId` was never in the request, so no value scan can catch
+ * it). On top of the value scan, each declared path's non-empty, non-virtual
+ * string gains the virtual shell of THIS request's server id; missing paths
+ * are no-ops and nothing is ever guessed beyond the declared positions.
+ *
+ * PB-25b widens the value scan's lookup from the request-local mapping to
+ * the request-local mapping UNION the KNOWN-real-session inventory: the
+ * merged global streams report every real id the sub-client currently holds
+ * (the sidebar's `zr~` rows — subagents.live's object keys, workflows.list
+ * rows: ids in the browser's view but not in THIS request), and a string
+ * exactly equal to one of those is rewritten too, in the same request-sourced
+ * virtual shell. The inventory is READ-ONLY consumption — the scan never
+ * touches merge state — and it is read live per answer: a stream refresh
+ * replaces its share, and the next answer sees the fresh union (ids that
+ * appear between two refreshes wait for the next refresh — the documented
+ * ceiling). Without the option the scan is exactly the PB-22 behavior.
+ *
  * The un-bridged refusals answer a UNIFORM 503 shape (header
  * `x-zen-remote: unbridged`, JSON body naming the reason) — and, decisive
  * for the security posture, they answer WITHOUT the local plugin handler
@@ -26,8 +61,8 @@
  */
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
-import type { BridgeRegistry, BridgeStatus } from './plugin-bridge.js'
-import { routeMethodsOf, routeMaxBodyOf, routeUpgradesOf } from './plugin-bridge.js'
+import type { BridgeLocator, BridgeRegistry, BridgeStatus, NormalizedBridgeRoute } from './plugin-bridge.js'
+import { routeDeniesRemoteOf, routeLocatorOf, routeMaxBodyOf, routeMethodsOf, routePrefixOf, routeRewriteFieldsOf, routeRewritesIdsOf, routeUpgradesOf } from './plugin-bridge.js'
 import { PassThrough, Readable, Transform } from 'node:stream'
 import type { Socket } from 'node:net'
 import type { RelayClient } from './relay-client.js'
@@ -47,6 +82,179 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+/** PB-22: the rewriteIds deep scan — every string in the parsed JSON that is
+ * EXACTLY a key of `known` becomes its virtual form; everything else passes
+ * through untouched. The mapping's membership is the ONLY rewrite trigger —
+ * no shape guessing (a session-id-LOOKING string the request never carried
+ * is not ours to rewrite), and object KEYS are left alone: the scan walks
+ * object values, array items and bare strings, exactly the positions a
+ * response can hand an id back to the browser in. Containers are rebuilt
+ * unconditionally, which keeps the rule obvious at the cost of allocations
+ * bounded by the 8 MB buffer cap.
+ *
+ * PB-25b adds the second lookup: a string exactly equal to a member of
+ * `knownIds` (the merged streams' known-real-session inventory, `undefined`
+ * when the wiring passed none — the scan then stays exactly the request-local
+ * behavior) is rewritten into THIS request's virtual shell, same source as
+ * the position rewrite's serverId. Already-virtual strings are never
+ * re-wrapped, and the set is read-only: the scan consults it, never mutates
+ * it. */
+function deepRewriteIds(
+  value: unknown,
+  known: ReadonlyMap<string, string>,
+  knownIds: ReadonlySet<string> | undefined,
+  serverId: string,
+): unknown {
+  if (typeof value === 'string') {
+    const mapped = known.get(value)
+    if (mapped !== undefined) return mapped
+    if (knownIds !== undefined && !isVirtual(value) && knownIds.has(value)) return toVirtual(serverId, value)
+    return value
+  }
+  if (Array.isArray(value)) return value.map((item) => deepRewriteIds(item, known, knownIds, serverId))
+  if (isRecord(value)) {
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value)) out[key] = deepRewriteIds(item, known, knownIds, serverId)
+    return out
+  }
+  return value
+}
+
+/** PB-25a: the position-based half of a `rewriteIds: { fields }` route's
+ * rewrite. Runs AFTER the value scan above, on the (rebuilt, private) parsed
+ * answer: each declared dot path is walked object-by-object, and a path that
+ * exists and holds a NON-EMPTY, NON-virtual string gains its virtual shell
+ * (`zr~<serverId>~<id>`, the serverId of the request this answer belongs to
+ * — a forward always located one). A path that does not exist — or that
+ * would walk through an array or a scalar — is a no-op: the answer's shape
+ * is the plugin's business, never a rewrite trigger (no shape guessing), and
+ * array elements stay the value scan's business (the declaration refuses
+ * numeric segments outright). Already-virtual values are skipped, so a known
+ * id sitting on a declared path is rewritten exactly once, by whichever half
+ * reached it first. */
+function rewriteIdsAtFields(root: unknown, fields: readonly string[], serverId: string): void {
+  for (const field of fields) {
+    const segments = field.split('.')
+    let node: unknown = root
+    for (const segment of segments.slice(0, -1)) {
+      node = isRecord(node) ? node[segment] : undefined
+    }
+    if (!isRecord(node)) continue
+    const key = segments[segments.length - 1]
+    const value = node[key]
+    if (typeof value === 'string' && value !== '' && !isVirtual(value)) node[key] = toVirtual(serverId, value)
+  }
+}
+
+/** Pump a response body reader into the browser response with real
+ * backpressure — the one discipline every verbatim passthrough runs. The
+ * `close` listener settles the wait when the browser vanishes mid-body (a
+ * lost drain event would otherwise hang the write loop). */
+async function pumpResponse(
+  res: ServerResponse,
+  reader: { read(): Promise<{ done: boolean; value?: Uint8Array }> },
+): Promise<void> {
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    if (!res.write(value)) {
+      await new Promise<void>((resolve) => {
+        const settled = (): void => {
+          res.off('drain', settled)
+          res.off('close', settled)
+          resolve()
+        }
+        res.once('drain', settled)
+        res.once('close', settled)
+      })
+    }
+  }
+}
+
+/** PB-22/PB-25a/PB-25b: a rewriteIds route's JSON answer — buffered whole
+ * (the 8 MB adapter cap), deep-scanned with the request's own real→virtual
+ * mapping PLUS the known-real-session inventory (read live by the caller),
+ * plus, when the route declared field paths, the position rewrite on those
+ * paths, re-serialized with a corrected content-length. Past the cap, a
+ * non-JSON content type, or a parse failure the answer passes through
+ * untouched (the adapter discipline): a rewrite is strictly
+ * better-than-nothing, never a reason to mangle or refuse an answer. The
+ * caller has already handled the relay's refusal marker — this owns the
+ * entire normal answer. */
+async function answerRewriteIds(
+  res: ServerResponse,
+  response: Response,
+  known: ReadonlyMap<string, string>,
+  fields: readonly string[] | undefined,
+  serverId: string,
+  knownIds: ReadonlySet<string> | undefined,
+): Promise<void> {
+  const contentType = response.headers.get('content-type')
+  const verbatimHeaders = {
+    ...(contentType !== null ? { 'content-type': contentType } : {}),
+    ...(response.headers.get('content-length') !== null ? { 'content-length': response.headers.get('content-length')! } : {}),
+    ...(response.headers.get('cache-control') !== null ? { 'cache-control': response.headers.get('cache-control')! } : {}),
+  }
+  const reader = response.body?.getReader()
+  if (reader === undefined || contentType === null || !contentType.includes('application/json')) {
+    res.writeHead(response.status, verbatimHeaders)
+    if (reader !== undefined) await pumpResponse(res, reader)
+    res.end()
+    return
+  }
+  const chunks: Buffer[] = []
+  let size = 0
+  let overflow = false
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.length
+    // The over-cap chunk ITSELF is body content — it lands in the
+    // passthrough buffer too; only the REWRITE is cancelled.
+    chunks.push(Buffer.from(value))
+    if (size > MAX_ADAPTER_RESPONSE_BUFFER_BYTES) {
+      overflow = true
+      break
+    }
+  }
+  if (overflow) {
+    res.writeHead(response.status, verbatimHeaders)
+    for (const chunk of chunks) {
+      if (!res.write(chunk)) {
+        await new Promise<void>((resolve) => {
+          const settled = (): void => {
+            res.off('drain', settled)
+            res.off('close', settled)
+            resolve()
+          }
+          res.once('drain', settled)
+          res.once('close', settled)
+        })
+      }
+    }
+    await pumpResponse(res, reader)
+    res.end()
+    return
+  }
+  const text = Buffer.concat(chunks).toString('utf8')
+  let outBody: Buffer
+  try {
+    const scanned = deepRewriteIds(JSON.parse(text), known, knownIds, serverId)
+    if (fields !== undefined) rewriteIdsAtFields(scanned, fields, serverId)
+    outBody = Buffer.from(JSON.stringify(scanned), 'utf8')
+  } catch {
+    // Not JSON after all (or the scan hit something unserializable): the
+    // original bytes pass through, length recomputed for the corrected
+    // header set.
+    outBody = Buffer.from(text, 'utf8')
+    res.writeHead(response.status, { ...verbatimHeaders, 'content-length': String(outBody.length) })
+    res.end(outBody)
+    return
+  }
+  res.writeHead(response.status, { ...verbatimHeaders, 'content-length': String(outBody.length) })
+  res.end(outBody)
+}
+
 /** Pure inspection of the RAW webServer instance — nothing is mutated, so a
  * failed check leaves every route exactly as it was. */
 export function checkWebServerShape(webServer: unknown): WebServerShapeCheck {
@@ -118,9 +326,23 @@ export interface InstallPluginRouteInterceptOptions {
    * read live per call). A VIRTUAL id means a remote session's panel is
    * the request's origin — the signal an adapter route's `deny` hook uses
    * to refuse requests (like better-sidebar's `open.external`) that carry
-   * no session field of their own. Absent → deny hooks see `undefined`
-   * and judge conservatively. */
+   * no session field of their own, and (PB-22) the same-origin wall a
+   * cooperative route's `deny: true` raises. Absent → deny judges
+   * conservatively (only the request's own ids speak). */
   getCurrentSession?: () => string | undefined
+  /** PB-25b: the KNOWN real session ids of this sub-client — the merged
+   * global streams' session inventories, unioned by the wiring. Read LIVE
+   * per rewriteIds answer, not captured at install: the streams report after
+   * the intercept installs, and a stream refresh replaces its share
+   * replace-style, so a getter is the only form that sees the fresh union —
+   * the same live-read discipline as getServerId/getStatus/getCurrentSession
+   * above. A rewriteIds route's value scan rewrites a string exactly equal
+   * to a member even when THIS request never carried it (the id already sits
+   * in the browser's view — subagents.live's object keys, workflows.list
+   * rows), wrapped in THIS request's virtual shell. The set is READ-ONLY
+   * consumption: nothing here mutates merge state. Absent → the scan is
+   * exactly the request-local PB-22 behavior. */
+  getKnownRealIds?: () => ReadonlySet<string>
   /** Progress logging, wired to the context logger by index.ts. */
   log?: (format: string, ...args: unknown[]) => void
 }
@@ -141,14 +363,59 @@ interface DeclaredHit {
   plugin: string
   version: string
   digest: string
-  /** The declared route path — the exact string the forward uses. */
+  /** The declared route path — what an exact route forwards verbatim (a
+   * prefix route forwards its full matched pathname instead). */
   path: string
-  sessionParam: string
+  /** The EFFECTIVE session-id locator (PB-21, {@link routeLocatorOf}): the
+   * declared locator, or the 2.1 query-parameter convention read as one —
+   * a route never runs without a locating rule. */
+  locator: BridgeLocator
+  /** The EFFECTIVE prefix mark (PB-21, {@link routePrefixOf}): the route
+   * admits its variable path tail. */
+  prefix: boolean
   /** The EFFECTIVE forwardable methods (PB-9): the declared list, or
    * `['GET']` when the route declared none. */
   methods: string[]
   /** The EFFECTIVE body cap (PB-9), in bytes. */
   maxBody: number
+  /** PB-22: the route refuses a REMOTE context outright (`deny: true` —
+   * local-only data): the surrogate answers `route-denied` instead of
+   * forwarding or passing through whenever the request carries a virtual id
+   * or the browser's current session is one. */
+  deny: boolean
+  /** PB-22: the route's JSON answers are deep-scanned for the request's own
+   * real session ids and re-serialized with their virtual forms. Both
+   * `rewriteIds` forms mark it true. */
+  rewriteIds: boolean
+  /** PB-25a: the declared field paths of a `{ fields }`-form `rewriteIds`
+   * route — where the response's NEWLY-CREATED session ids sit. `undefined`
+   * for a `true` route (value scan only) and for a route without the field. */
+  rewriteFields: readonly string[] | undefined
+  /** The same effective values folded into the adapter-core route shape —
+   * the object locate/classify/rewrite consume (PB-21, see
+   * {@link bridgeRouteAsAdapterRoute}). */
+  view: NormalizedAdapterRoute
+}
+
+/** The NormalizedBridgeRoute read through the adapter-core route shapes
+ * (PB-21): the declaration-v2 locators must ride the SAME locate →
+ * classify → rewrite functions the adapters run — never a second copy of
+ * those rules — so the cooperative route is handed to them as the
+ * NormalizedAdapterRoute those functions consume. Every field comes from a
+ * plugin-bridge effective reader; `deny` stays unset — the cooperative
+ * `deny: true` flag is a static declaration, not an adapter-style hook, so
+ * the surrogate halves judge it themselves (PB-22). */
+function bridgeRouteAsAdapterRoute(route: NormalizedBridgeRoute): NormalizedAdapterRoute {
+  return {
+    path: route.path,
+    match: routePrefixOf(route) ? 'prefix' : 'exact',
+    methods: routeMethodsOf(route),
+    maxBody: routeMaxBodyOf(route),
+    stream: route.stream,
+    upgrade: routeUpgradesOf(route),
+    locator: routeLocatorOf(route),
+    local: false,
+  }
 }
 
 export function installPluginRouteIntercept(options: InstallPluginRouteInterceptOptions): PluginRouteInterceptHandle {
@@ -182,6 +449,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
   const { webServer, registry, relay, getServerId, getStatus, log } = options
   const adapters = options.adapters ?? []
   const getCurrentSession = options.getCurrentSession
+  const getKnownRealIds = options.getKnownRealIds
   const target = webServer as { match: (this: unknown, pathname: string) => unknown }
   const savedMatch = target.match
 
@@ -244,30 +512,42 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
       ? (route as { handler: (req: IncomingMessage, res: ServerResponse) => Promise<void> }).handler
       : undefined
 
-  /** The declared route this pathname hits — EXACT equality only this task
-   * (a declared prefix does not cover longer paths; that arrives with
-   * PB-12). First plugin in registry order wins, deterministically. */
+  /** The declared route this pathname hits — exact equality, or, for a
+   * route declared `prefix: true` (PB-21), equality or one path segment
+   * deeper on the RAW undecoded pathname. The rule is `adapterPathMatches`
+   * itself, run against the route's adapter-core view, so the cooperative
+   * match can never drift from the adapters'. First plugin in registry
+   * order wins, and within it the first route in declaration order — a
+   * pathname two routes of one plugin can both hit belongs to the earlier
+   * one, exactly as the exact-only lookup always did. */
   const declaredRouteOf = (pathname: string): DeclaredHit | undefined => {
     for (const declaration of registry.list()) {
       for (const route of declaration.routes) {
-        if (route.path === pathname) {
-          return {
-            plugin: declaration.plugin,
-            version: declaration.version,
-            digest: declaration.digest,
-            path: route.path,
-            sessionParam: route.sessionParam,
-            methods: routeMethodsOf(route),
-            maxBody: routeMaxBodyOf(route),
-          }
+        const view = bridgeRouteAsAdapterRoute(route)
+        if (!adapterPathMatches(view, pathname)) continue
+        return {
+          plugin: declaration.plugin,
+          version: declaration.version,
+          digest: declaration.digest,
+          path: route.path,
+          locator: routeLocatorOf(route),
+          prefix: routePrefixOf(route),
+          methods: routeMethodsOf(route),
+          maxBody: routeMaxBodyOf(route),
+          deny: routeDeniesRemoteOf(route),
+          rewriteIds: routeRewritesIdsOf(route),
+          rewriteFields: routeRewriteFieldsOf(route),
+          view,
         }
       }
     }
     return undefined
   }
 
-  /** The surrogate handler: ONE query parse, the virtual-id gate, the
-   * unbridged walls in contract order, then the relay round-trip. */
+  /** The surrogate handler, query locator's half (every 2.1 route and an
+   * explicit query declaration): ONE query parse, the virtual-id gate, the
+   * unbridged walls in contract order, then the relay round-trip. A
+   * declaration-v2 locator dispatches to the PB-21 half below. */
   const surrogateHandler = (declared: DeclaredHit, originalHandler: ((req: IncomingMessage, res: ServerResponse) => Promise<void>) | undefined) =>
     async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
       const passthrough = async (): Promise<void> => {
@@ -284,16 +564,28 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         await passthrough()
         return
       }
+      // PB-21: a v2 locator (path-segment / json-body) runs the adapter-core
+      // pipeline in its own half — the query locator keeps THIS code path
+      // verbatim. The dispatch sits after the installed check, so the v2
+      // half never runs chained-over either.
+      if (declared.locator.in !== 'query') {
+        await surrogateV2Handler(declared, originalHandler)(req, res)
+        return
+      }
       // ONE parse of the query (the session parameter's home — `match` only
-      // ever saw the pathname): everything below reads THIS parse.
-      let searchParams: URLSearchParams
+      // ever saw the pathname): everything below reads THIS parse. The
+      // parameter NAME is the effective locator's (the 2.1 sessionParam for
+      // a route that declared no locator — the same value routeLocatorOf
+      // reads back out).
+      let requestUrl: URL
       try {
-        searchParams = new URL(req.url ?? '/', 'http://local').searchParams
+        requestUrl = new URL(req.url ?? '/', 'http://local')
       } catch {
         answerUnbridged(res, declared.plugin, 'bad-query')
         return
       }
-      const values = searchParams.getAll(declared.sessionParam)
+      const searchParams = requestUrl.searchParams
+      const values = searchParams.getAll(declared.locator.name)
       // The parameter appearing MORE than once is a shape violation the
       // bridge refuses (bad-query) — never a passthrough, and never a
       // forward of whichever duplicate a parser happens to keep. Its TOTAL
@@ -304,6 +596,20 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         return
       }
       const value = values.length === 1 ? values[0] : undefined
+      // PB-22: a `deny: true` route refuses a REMOTE context outright — the
+      // request locating a virtual id, or the browser's CURRENT session
+      // being one (T62's signal; requests like open.external carry no id of
+      // their own). The uniform 503 with the route's own reason: the local
+      // handler is never reached, and the forward path below is unreachable
+      // for this route. A local session's request without a virtual id falls
+      // through — `deny` must not touch local behavior.
+      if (declared.deny) {
+        const current = getCurrentSession?.()
+        if ((current !== undefined && isVirtual(current)) || (value !== undefined && value.startsWith('zr~'))) {
+          answerUnbridged(res, declared.plugin, 'route-denied')
+          return
+        }
+      }
       // A LOCAL id (or none at all): the original route's business — its
       // handler runs exactly as if we were never here.
       if (value === undefined || value === '' || !value.startsWith('zr~')) {
@@ -354,7 +660,15 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
       log?.('plugin route %s forwards for %s', declared.path, declared.plugin)
       // The session id rides the CHECKED parse, restored to its ORIGINAL
       // form, re-serialized once — what was judged is what is forwarded.
-      searchParams.set(declared.sessionParam, parts.id)
+      searchParams.set(declared.locator.name, parts.id)
+      // PB-22: the request's own real→virtual pair — the READ-ONLY mapping a
+      // rewriteIds route's answer scan consults (`zr~` carries the real id
+      // inside, so the ids this very request named are exactly the ones the
+      // answer may hand back). PB-25b: the scan consults ONE more source
+      // beside this mapping — the known-real-session inventory, read live at
+      // the answer (never copied here) and consumed read-only; nothing here
+      // writes any session table.
+      const idMapping: ReadonlyMap<string, string> = new Map([[parts.id, value]])
       const controller = new AbortController()
       // The counting gate's failure has its OWN abort signal (PB-9-fix, the
       // mirror of the relay route's bodyGateError): tripping the gate is a
@@ -408,7 +722,11 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
             plugin: declared.plugin,
             version: declared.version,
             digest: declared.digest,
-            path: declared.path,
+            // A prefix route (PB-21) forwards its FULL matched pathname —
+            // the declared base alone would lose the variable tail; an
+            // exact route's pathname IS the declared path, the bytes that
+            // always travelled.
+            path: declared.prefix ? requestUrl.pathname : declared.path,
             query: searchParams.toString(),
             method,
             ...(hasBody ? { body: bodyStream } : {}),
@@ -428,6 +746,17 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           answerUnbridged(res, declared.plugin, refusal)
           return
         }
+        // PB-22: a rewriteIds route's answer is buffered and deep-scanned
+        // (the ids this request named come back virtual); everything else —
+        // non-JSON answers included — streams verbatim. PB-25a: a
+        // `{ fields }` declaration adds the position rewrite, under THIS
+        // request's own server id. PB-25b: the scan's lookup widens to the
+        // known inventory, read live right here (undefined when the wiring
+        // passed no getter — the scan stays request-local).
+        if (declared.rewriteIds) {
+          await answerRewriteIds(res, response, idMapping, declared.rewriteFields, parts.serverId, getKnownRealIds?.())
+          return
+        }
         const contentType = response.headers.get('content-type')
         const contentLength = response.headers.get('content-length')
         const cacheControl = response.headers.get('cache-control')
@@ -439,23 +768,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
         // Stream the body through with real backpressure; a mid-stream
         // failure with headers already out can only cut the response.
         const reader = response.body?.getReader()
-        if (reader !== undefined) {
-          while (true) {
-            const { done, value } = await reader.read()
-            if (done) break
-            if (!res.write(value)) {
-              await new Promise<void>((resolve) => {
-                const settled = (): void => {
-                  res.off('drain', settled)
-                  res.off('close', settled)
-                  resolve()
-                }
-                res.once('drain', settled)
-                res.once('close', settled)
-              })
-            }
-          }
-        }
+        if (reader !== undefined) await pumpResponse(res, reader)
         res.end()
       } catch (error) {
         // The gate's local flag FIRST (PB-9-fix): the counting gate tripped
@@ -492,6 +805,304 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
       }
     }
 
+  /** The PB-21 surrogate half for the declaration-v2 locators — json-body,
+   * and path-segment on a prefix route: the adapter surrogate's pipeline
+   * (locate → classify → walls → rewrite → the relay round-trip) run
+   * through the SAME adapter-core functions against the route's
+   * adapter-core view. The response discipline stays the query half's —
+   * three headers, no hooks: `deny` and `rewriteIds` are PB-22's business.
+   * Dispatch above guarantees `installed` and a non-query locator. */
+  const surrogateV2Handler = (declared: DeclaredHit, originalHandler: ((req: IncomingMessage, res: ServerResponse) => Promise<void>) | undefined) =>
+    async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+      const plugin = declared.plugin
+      // The local passthrough. A json-body route has ALREADY consumed the
+      // request body by the time this runs (the classify needs the parsed
+      // body), so the replay hands the buffered bytes back behind the
+      // original request's metadata — the shape a local handler actually
+      // reads (method/url/headers/pipe).
+      const passthrough = async (replayBody?: Buffer): Promise<void> => {
+        if (originalHandler === undefined) {
+          res.writeHead(404)
+          res.end()
+          return
+        }
+        if (replayBody !== undefined) {
+          const replay = new PassThrough()
+          replay.end(replayBody)
+          Object.assign(replay, { method: req.method, url: req.url, headers: req.headers })
+          await originalHandler(replay as unknown as IncomingMessage, res)
+          return
+        }
+        await originalHandler(req, res)
+      }
+      let controller: AbortController | undefined
+      const onClientGone = (): void => {
+        if (controller !== undefined && !res.writableEnded) controller.abort()
+      }
+      res.on('close', onClientGone)
+      // The counting gate's LOCAL flag (the query half's PB-9-fix shape): a
+      // tripped gate answers the local 413 in the catch below — never an
+      // offline verdict, never a half-written response.
+      let bodyGateFailed = false
+      const bodyAbort = new AbortController()
+      try {
+        let url: URL
+        try {
+          url = new URL(req.url ?? '/', 'http://local')
+        } catch {
+          answerUnbridged(res, plugin, 'bad-query')
+          return
+        }
+        const pathname = url.pathname
+        const searchParams = url.searchParams
+        const method = req.method ?? 'GET'
+        const hasBody = method !== 'GET' && method !== 'HEAD'
+
+        // PB-22: the deny wall's current-session half — a remote panel is
+        // the request's origin even when it carries no id of its own
+        // (open.external's shape). Refused before any body byte is read.
+        if (declared.deny) {
+          const current = getCurrentSession?.()
+          if (current !== undefined && isVirtual(current)) {
+            answerUnbridged(res, plugin, 'route-denied')
+            return
+          }
+        }
+
+        // A json-body route buffers the request body up front, bounded by
+        // the route's own maxBody — the cooperative 413 shape, answered
+        // locally, the plugin never reached. A path-segment route's body is
+        // never consumed by locating; it streams through the counting gate
+        // at the forward.
+        let bufferedBody: Buffer | undefined
+        if (hasBody && declared.locator.in === 'json-body') {
+          const chunks: Buffer[] = []
+          let size = 0
+          let over = false
+          for await (const chunk of req) {
+            size += (chunk as Buffer).length
+            if (size > declared.maxBody) {
+              over = true
+              break
+            }
+            chunks.push(Buffer.from(chunk as Uint8Array))
+          }
+          if (over) {
+            res.setHeader('content-type', 'application/json; charset=utf-8')
+            res.writeHead(413)
+            res.end(JSON.stringify({ ok: false, error: { code: 'zr-plugin-body-too-large' } }))
+            recordRefusal(plugin, 'body-too-large')
+            log?.('plugin request for %s refused locally: body-too-large (%s buffered)', declared.path, size)
+            return
+          }
+          bufferedBody = Buffer.concat(chunks)
+        }
+        // A present body must parse as JSON when the route locates in it —
+        // a corrupted body refuses rather than falling through to the local
+        // plugin with a body the locate could not judge (the adapter half's
+        // shared rule).
+        let parsedBody: unknown
+        let bodyGiven = false
+        if (hasBody && declared.locator.in === 'json-body' && bufferedBody !== undefined && bufferedBody.length > 0) {
+          try {
+            parsedBody = JSON.parse(bufferedBody.toString('utf8'))
+            bodyGiven = true
+          } catch {
+            answerUnbridged(res, plugin, 'bad-query')
+            return
+          }
+        }
+        // The remote/local verdict on the ids as they arrived — the
+        // adapter-core classify (locate inside), no second copy of the
+        // rule: every id virtual → forward, none → local, a mix → the
+        // uniform refusal (docs/adr/0001: a remote session never reaches a
+        // local plugin).
+        let verdict: AdapterRemoteVerdict
+        try {
+          verdict = classifyAdapterRequest(declared.view, pathname, searchParams, bodyGiven ? parsedBody : undefined)
+        } catch (error) {
+          if (error instanceof AdapterMultiValueQueryError) {
+            answerUnbridged(res, plugin, 'bad-query')
+            return
+          }
+          throw error
+        }
+        // PB-22: the deny wall's request half — the locate found a virtual
+        // id (a remote verdict, or a mixed one: that too means a virtual id
+        // sat in the request). This route never serves a remote context, so
+        // the answer is the route's own refusal, not the mixed shape.
+        if (declared.deny && verdict.kind !== 'local') {
+          answerUnbridged(res, plugin, 'route-denied')
+          return
+        }
+        if (verdict.kind === 'local') {
+          await passthrough(bufferedBody)
+          return
+        }
+        if (verdict.kind === 'mixed') {
+          answerUnbridged(res, plugin, 'bad-query')
+          return
+        }
+        // Remote: the route's method wall, then the per-id server walls —
+        // the query half's gates, re-run per located id.
+        if (!declared.methods.includes(method)) {
+          answerUnbridged(res, plugin, 'method-not-bridged')
+          return
+        }
+        const serverId = getServerId()
+        // PB-22: the request's own real→virtual pairs, collected while the
+        // wall validates each hit — the READ-ONLY mapping a rewriteIds
+        // route's answer scan consults (`zr~` carries the real id inside, so
+        // the ids this very request named are exactly the ones the answer
+        // may hand back). PB-25a: the SAME unwrap hands the position rewrite
+        // its server id — the ids this request located live under it, so a
+        // NEWLY-created id joins them (the query half's source verbatim;
+        // `remote` always has at least one hit). PB-25b: the scan consults
+        // ONE more source beside this mapping — the known-real-session
+        // inventory, read live at the answer (never copied here) and
+        // consumed read-only; nothing here writes any session table.
+        const idMapping = new Map<string, string>()
+        let locatedServerId: string | undefined
+        for (const idHit of verdict.hits) {
+          const parts = fromVirtual(idHit.value)
+          if (parts === undefined || parts.id === '') {
+            answerUnbridged(res, plugin, 'bad-query')
+            return
+          }
+          if (parts.serverId !== serverId) {
+            answerUnbridged(res, plugin, 'server-changed')
+            return
+          }
+          idMapping.set(parts.id, idHit.value)
+          locatedServerId = parts.serverId
+        }
+        // The bridge verdicts judged from the SAME live table the query
+        // half reads.
+        const status = getStatus().find((entry) => entry.plugin === plugin)
+        if (status === undefined || !status.bridged) {
+          answerUnbridged(res, plugin, status?.reason ?? 'not-on-server')
+          return
+        }
+        // Real ids in, coordinates rewritten — the adapter-core rewrite:
+        // the query re-serialized, the path segment re-encoded, the JSON
+        // body re-serialized. The forward carries the REWRITTEN pathname —
+        // a prefix route's full matched path, never the declared base.
+        const rewrite = rewriteAdapterRequest(declared.view, pathname, searchParams, bodyGiven ? parsedBody : undefined, verdict.hits, (virtualId) => fromVirtual(virtualId)!.id)
+        forwarded += 1
+        log?.('plugin route %s forwards for %s', rewrite.pathname, plugin)
+        controller = new AbortController()
+        const forwardSignal = AbortSignal.any([controller.signal, bodyAbort.signal])
+        const accept = typeof req.headers.accept === 'string' ? req.headers.accept : undefined
+        const range = typeof req.headers.range === 'string' ? req.headers.range : undefined
+        const requestContentType = typeof req.headers['content-type'] === 'string' ? req.headers['content-type'] : undefined
+        const declaredLength = Number(req.headers['content-length'])
+        let bodyStream: ReadableStream<Uint8Array> | null = null
+        let contentLength: number | undefined
+        if (hasBody && declared.locator.in === 'json-body') {
+          // The buffer forwards in full: the (possibly rewritten)
+          // re-serialization when ids sat in it, the original bytes
+          // otherwise. The REWRITTEN byte count is the declared length —
+          // the budget reads what actually travels.
+          const payload = rewrite.bodyText !== undefined ? Buffer.from(rewrite.bodyText, 'utf8') : bufferedBody ?? Buffer.alloc(0)
+          contentLength = payload.length
+          bodyStream = Readable.toWeb(Readable.from(payload)) as ReadableStream<Uint8Array>
+        } else if (hasBody) {
+          // The pre-check first — a DECLARED Content-Length past the cap
+          // never starts a round-trip — then the counting gate for a
+          // chunked body, exactly the query half's PB-9 discipline.
+          if (Number.isFinite(declaredLength) && declaredLength > declared.maxBody) {
+            res.setHeader('content-type', 'application/json; charset=utf-8')
+            res.writeHead(413)
+            res.end(JSON.stringify({ ok: false, error: { code: 'zr-plugin-body-too-large' } }))
+            recordRefusal(plugin, 'body-too-large')
+            log?.('plugin request for %s refused locally: body-too-large (%s declared)', declared.path, req.headers['content-length'])
+            return
+          }
+          let pumped = 0
+          const gate = new Transform({
+            transform(chunk: Buffer, _encoding, callback) {
+              pumped += chunk.length
+              if (pumped > declared.maxBody) {
+                callback(new Error('zr-plugin-body-too-large'))
+                return
+              }
+              callback(null, chunk)
+            },
+          })
+          req.on('error', (error) => gate.destroy(error))
+          gate.on('error', () => {
+            if (!bodyGateFailed) bodyGateFailed = true
+            bodyAbort.abort()
+          })
+          bodyStream = Readable.toWeb(gate) as ReadableStream<Uint8Array>
+          req.pipe(gate)
+          if (Number.isFinite(declaredLength) && declaredLength > 0) contentLength = declaredLength
+        }
+        const response = await relay.pluginRequest(
+          {
+            plugin,
+            version: declared.version,
+            digest: declared.digest,
+            path: rewrite.pathname,
+            query: rewrite.query.toString(),
+            method,
+            ...(bodyStream !== null ? { body: bodyStream } : {}),
+            ...(bodyStream !== null && requestContentType !== undefined ? { contentType: requestContentType } : {}),
+            ...(bodyStream !== null && contentLength !== undefined ? { contentLength } : {}),
+            ...(accept !== undefined ? { accept } : {}),
+            ...(range !== undefined ? { range } : {}),
+          },
+          forwardSignal,
+        )
+        // Down from here the query half's response discipline verbatim: the
+        // relay refusal marker, the three cooperative headers, the pump
+        // with real backpressure — plus (PB-22) the rewriteIds branch.
+        const refusal = response.headers.get('x-zen-remote-error')
+        if (refusal !== null) {
+          await response.body?.cancel().catch(() => {})
+          answerUnbridged(res, plugin, refusal)
+          return
+        }
+        if (declared.rewriteIds) {
+          await answerRewriteIds(res, response, idMapping, declared.rewriteFields, locatedServerId!, getKnownRealIds?.())
+          return
+        }
+        const contentType = response.headers.get('content-type')
+        const responseLength = response.headers.get('content-length')
+        const cacheControl = response.headers.get('cache-control')
+        res.writeHead(response.status, {
+          ...(contentType !== null ? { 'content-type': contentType } : {}),
+          ...(responseLength !== null ? { 'content-length': responseLength } : {}),
+          ...(cacheControl !== null ? { 'cache-control': cacheControl } : {}),
+        })
+        const reader = response.body?.getReader()
+        if (reader !== undefined) await pumpResponse(res, reader)
+        res.end()
+      } catch (error) {
+        // The gate's local flag first (the query half's shape): the 413
+        // still fits while the browser's headers are not out.
+        if (bodyGateFailed && !res.headersSent) {
+          res.setHeader('content-type', 'application/json; charset=utf-8')
+          res.writeHead(413)
+          res.end(JSON.stringify({ ok: false, error: { code: 'zr-plugin-body-too-large' } }))
+          recordRefusal(plugin, 'body-too-large')
+          return
+        }
+        if (controller?.signal.aborted || res.destroyed || res.headersSent) {
+          try {
+            res.destroy()
+          } catch {
+            // Already gone.
+          }
+          return
+        }
+        const code = typeof (error as { code?: unknown } | null)?.code === 'string' ? (error as { code: string }).code : 'offline'
+        answerUnbridged(res, plugin, code === 'aborted' ? 'offline' : code)
+      } finally {
+        res.off('close', onClientGone)
+      }
+    }
+
   // ---- PB-11: the adapter interception ---------------------------------------
   //
   // An adapter (src/adapters/, validated into a NormalizedAdapter by the
@@ -769,23 +1380,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
             ...Object.assign({}, ...allowlistedHeaders),
           })
           const reader = response.body?.getReader()
-          if (reader !== undefined) {
-            while (true) {
-              const { done, value } = await reader.read()
-              if (done) break
-              if (!res.write(value)) {
-                await new Promise<void>((resolve) => {
-                  const settled = (): void => {
-                    res.off('drain', settled)
-                    res.off('close', settled)
-                    resolve()
-                  }
-                  res.once('drain', settled)
-                  res.once('close', settled)
-                })
-              }
-            }
-          }
+          if (reader !== undefined) await pumpResponse(res, reader)
           res.end()
           return
         }
@@ -829,21 +1424,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
               })
             }
           }
-          while (true) {
-            const { done, value } = await reader.read()
-            if (done) break
-            if (!res.write(value)) {
-              await new Promise<void>((resolve) => {
-                const settled = (): void => {
-                  res.off('drain', settled)
-                  res.off('close', settled)
-                  resolve()
-                }
-                res.once('drain', settled)
-                res.once('close', settled)
-              })
-            }
-          }
+          await pumpResponse(res, reader)
           res.end()
           return
         }
@@ -897,9 +1478,10 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
   /** The wrapped match: original verdict first, then the adapter routes
    * (PB-11 — BEFORE the declaration lookup: the adapter's registry entry
    * IS a declaration, and the cooperative surrogate's query-sessionParam
-   * logic is not how an adapter request is judged), then the exact
-   * declaration lookup — an undeclared pathname returns whatever the
-   * original match answered, untouched. */
+   * logic is not how an adapter request is judged), then the declaration
+   * lookup — exact paths plus (PB-21) a declared prefix route's full
+   * match. An undeclared pathname returns whatever the original match
+   * answered, untouched. */
   const wrappedMatch = function match(this: unknown, pathname: string): unknown {
     const route = savedMatch.call(this, pathname)
     if (!installed) return route
@@ -937,7 +1519,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
 
   const targetWithUpgrades = webServer as { upgrades: Map<string, unknown> }
   const savedUpgradesGet = targetWithUpgrades.upgrades.get
-  const upgradeRoutesOf = (pathname: string): { plugin: string; version: string; digest: string; path: string; sessionParam: string } | undefined => {
+  const upgradeRoutesOf = (pathname: string): { plugin: string; version: string; digest: string; path: string; sessionParam: string; deny: boolean } | undefined => {
     if (!installed) return undefined
     for (const declaration of registry.list()) {
       for (const route of declaration.routes) {
@@ -948,6 +1530,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
             digest: declaration.digest,
             path: route.path,
             sessionParam: route.sessionParam,
+            deny: routeDeniesRemoteOf(route),
           }
         }
       }
@@ -957,7 +1540,7 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
 
   /** The tunnel's surrogate upgrade handler. Every outcome — refusal,
    * teardown, the byte pumping — owns the socket's whole remaining life. */
-  const surrogateUpgrade = (declared: { plugin: string; version: string; digest: string; path: string; sessionParam: string }, originalHandler: unknown) =>
+  const surrogateUpgrade = (declared: { plugin: string; version: string; digest: string; path: string; sessionParam: string; deny: boolean }, originalHandler: unknown) =>
     (req: IncomingMessage, socket: Socket, head: Buffer): void => {
       // The host never awaits an upgrade handler — the async body runs on
       // its own and every failure path owns the socket's teardown.
@@ -990,6 +1573,18 @@ export function installPluginRouteIntercept(options: InstallPluginRouteIntercept
           return
         }
         const value = values.length === 1 ? values[0] : undefined
+        // PB-22: the deny wall on the tunnel — the HTTP surrogate's rule
+        // verbatim. A remote context (the request's own virtual id, or the
+        // browser's reported current session) never opens a byte tunnel into
+        // a route declared `deny: true`; a local session's upgrade passes
+        // through untouched.
+        if (declared.deny) {
+          const current = getCurrentSession?.()
+          if ((current !== undefined && isVirtual(current)) || (value !== undefined && value.startsWith('zr~'))) {
+            answerUnbridgedSocket(socket, declared.plugin, 'route-denied')
+            return
+          }
+        }
         // A LOCAL session (or no parameter at all): the original upgrade
         // handler's business, the head bytes untouched.
         if (value === undefined || value === '' || !value.startsWith('zr~')) {