dsh-zen-remote 2.3.3 → 2.3.5

package/lib/plugin-route-intercept.js

@@ -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
@@ -24,13 +59,178 @@
  * and ours goes inert instead (the same posture as intercept.ts and
  * fetch-route-intercept.ts).
  */
-import { routeMethodsOf, routeMaxBodyOf, routeUpgradesOf } 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 { fromVirtual, isVirtual, toVirtual } from './virtual-id.js';
 import { adapterPathMatches, classifyAdapterRequest, rewriteAdapterRequest, adapterOwnsRegistryEntry, MAX_ADAPTER_RESPONSE_BUFFER_BYTES, ADAPTER_RESPONSE_HEADER_ALLOWLIST, AdapterMultiValueQueryError } from './plugin-adapter-core.js';
 function isRecord(value) {
     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, known, knownIds, serverId) {
+    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 = {};
+        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, fields, serverId) {
+    for (const field of fields) {
+        const segments = field.split('.');
+        let node = 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, reader) {
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!res.write(value)) {
+            await new Promise((resolve) => {
+                const settled = () => {
+                    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, response, known, fields, serverId, knownIds) {
+    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 = [];
+    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((resolve) => {
+                    const settled = () => {
+                        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;
+    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) {
@@ -51,6 +251,26 @@ export function checkWebServerShape(webServer) {
 }
 /** Longest failure ring kept for the status surface. */
 const MAX_FAILURES = 10;
+/** 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) {
+    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) {
     // Shape FIRST, like every wrap: a caller that skipped checkWebServerShape
     // (or a host whose shape changed between the check and this call) gets an
@@ -82,6 +302,7 @@ export function installPluginRouteIntercept(options) {
     const { webServer, registry, relay, getServerId, getStatus, log } = options;
     const adapters = options.adapters ?? [];
     const getCurrentSession = options.getCurrentSession;
+    const getKnownRealIds = options.getKnownRealIds;
     const target = webServer;
     const savedMatch = target.match;
     let installed = true;
@@ -137,29 +358,42 @@ export function installPluginRouteIntercept(options) {
     const handlerOf = (route) => route !== undefined && isRecord(route) && typeof route.handler === 'function'
         ? route.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) => {
         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, originalHandler) => async (req, res) => {
         const passthrough = async () => {
             if (originalHandler !== undefined) {
@@ -175,17 +409,29 @@ export function installPluginRouteIntercept(options) {
             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;
+        // 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;
         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
@@ -196,6 +442,20 @@ export function installPluginRouteIntercept(options) {
             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~')) {
@@ -246,7 +506,15 @@ export function installPluginRouteIntercept(options) {
         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 = 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
@@ -301,7 +569,11 @@ export function installPluginRouteIntercept(options) {
                 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 } : {}),
@@ -319,6 +591,17 @@ export function installPluginRouteIntercept(options) {
                 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');
@@ -330,24 +613,8 @@ export function installPluginRouteIntercept(options) {
             // 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((resolve) => {
-                            const settled = () => {
-                                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) {
@@ -386,6 +653,308 @@ export function installPluginRouteIntercept(options) {
             res.off('close', onClientGone);
         }
     };
+    /** 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, originalHandler) => async (req, res) => {
+        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) => {
+            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, res);
+                return;
+            }
+            await originalHandler(req, res);
+        };
+        let controller;
+        const onClientGone = () => {
+            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;
+            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;
+            if (hasBody && declared.locator.in === 'json-body') {
+                const chunks = [];
+                let size = 0;
+                let over = false;
+                for await (const chunk of req) {
+                    size += chunk.length;
+                    if (size > declared.maxBody) {
+                        over = true;
+                        break;
+                    }
+                    chunks.push(Buffer.from(chunk));
+                }
+                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;
+            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;
+            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();
+            let locatedServerId;
+            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 = null;
+            let contentLength;
+            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));
+            }
+            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, _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);
+                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?.code === 'string' ? error.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
@@ -662,24 +1231,8 @@ export function installPluginRouteIntercept(options) {
                     ...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((resolve) => {
-                                const settled = () => {
-                                    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;
             }
@@ -724,22 +1277,7 @@ export function installPluginRouteIntercept(options) {
                         });
                     }
                 }
-                while (true) {
-                    const { done, value } = await reader.read();
-                    if (done)
-                        break;
-                    if (!res.write(value)) {
-                        await new Promise((resolve) => {
-                            const settled = () => {
-                                res.off('drain', settled);
-                                res.off('close', settled);
-                                resolve();
-                            };
-                            res.once('drain', settled);
-                            res.once('close', settled);
-                        });
-                    }
-                }
+                await pumpResponse(res, reader);
                 res.end();
                 return;
             }
@@ -796,9 +1334,10 @@ export function installPluginRouteIntercept(options) {
     /** 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(pathname) {
         const route = savedMatch.call(this, pathname);
         if (!installed)
@@ -848,6 +1387,7 @@ export function installPluginRouteIntercept(options) {
                         digest: declaration.digest,
                         path: route.path,
                         sessionParam: route.sessionParam,
+                        deny: routeDeniesRemoteOf(route),
                     };
                 }
             }
@@ -890,6 +1430,18 @@ export function installPluginRouteIntercept(options) {
                     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~')) {