dsh-zen-remote 2.2.4 → 2.2.6

package/src/fetch-route-intercept.ts

@@ -59,7 +59,7 @@ export const FILE_UPLOAD_PATH = '/api/session/uploadFileBinary'
  * lib/index.js:488). */
 export const SESSION_EXPORT_PATH = '/api/session.export'
 
-/** The remote upload cap, the relay's own 100 MiB (relay-server.ts explains
+/** The remote upload cap, the relay's own 500 MiB (relay-server.ts explains
  * why the host has no number to mirror). Interpolated into the local
  * oversize refusal so the card names the real limit. */
 const UPLOAD_CAP_MIB = Math.floor(MAX_UPLOAD_BYTES / (1024 * 1024))

package/src/index.ts

@@ -15,8 +15,8 @@
  * the package.json dsh.client declaration.
  */
 
-import { createOwnerPeerSource } from './owner-peer.js'
-import { lstat, mkdir, open, realpath, rm } from 'node:fs/promises'
+import { createOwnerPeerSource, createSharedApiFetchGetter } from './owner-peer.js'
+import { lstat, mkdir, open, realpath, rm, writeFile } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { randomBytes } from 'node:crypto'
@@ -307,9 +307,27 @@ async function ensureManagedDirectory(workspace: string, path: string): Promise<
   if (!entry.isDirectory()) throw new UploadError(400, 'path-escape', `upload path is not a directory: ${path}`)
   const canonical = await realpath(path)
   ensurePathInside(workspace, canonical)
+  await ensureSelfIgnoring(canonical)
   return canonical
 }
 
+/**
+ * Drop a self-ignoring `.gitignore` (`*` + `!.gitignore`) next to the
+ * upload directory's creation, so dropped files never surface as untracked
+ * entries in the session workspace — an agent's `git add -A` would
+ * otherwise commit the user's uploads. `wx` keeps a pre-existing
+ * (user-customized) file untouched; in a non-git workspace the file is an
+ * inert no-op. Best-effort only: a read-only directory still receives the
+ * upload route's own error, never a new one from here.
+ */
+async function ensureSelfIgnoring(directory: string): Promise<void> {
+  try {
+    await writeFile(join(directory, '.gitignore'), '*\n!.gitignore\n', { flag: 'wx', mode: 0o644 })
+  } catch (error) {
+    if (!isErrnoCode(error, 'EEXIST') && !isErrnoCode(error, 'EROFS') && !isErrnoCode(error, 'EACCES')) throw error
+  }
+}
+
 interface UploadRoot {
   /** Canonical directory the bytes are written into. */
   writeRoot: string
@@ -492,6 +510,39 @@ export async function handleUpload(
  */
 export function apply(ctx: Context, config: MobileNavConfig = {}): void {
   const effective = resolveConfig(config, readFileConfig(), process.env)
+  // RD-6 probe fact: whether the fetch-route inject callback (below, in the
+  // client-half wiring) ever fired. On a composition where `connection` or
+  // `fileUploads` never becomes available the callback stays silently
+  // PENDING (cordis waits forever, printing nothing) and every fetch-route
+  // diagnostic stays undefined — this flag is the one honest signal of that
+  // state. Declared this early because probes on BOTH role branches read it.
+  let fetchRouteInjectSeen = false
+  /** The client branch's fetch-route diagnostics getter, assigned once that
+   * branch declares it; the probe reads it lazily through this slot so both
+   * role mounts can share one probe factory. */
+  let fetchRouteDiagnosticsRef: (() => unknown) | undefined
+  /** RD-6: build the lazy service probe against a context whose own inject
+   * already resolved (the client-routes mounts qualify on both roles). One
+   * reflection per process: `connection` / `fileUploads` presence plus the
+   * fetchRoutes table's shape — enough to name the missing service. */
+  const uploadServiceProbe = (probeCtx: Context): (() => Record<string, unknown>) => {
+    let cached: Record<string, unknown> | undefined
+    return () => {
+      if (cached !== undefined) return cached
+      const reflect = (probeCtx as Context & { reflect?: { get(name: string): unknown } }).reflect
+      const connection = reflect?.get('connection')
+      const fileUploads = reflect?.get('fileUploads')
+      const fetchRoute = fetchRouteDiagnosticsRef?.()
+      cached = {
+        uploadInjectSeen: fetchRouteInjectSeen,
+        connectionService: connection === undefined ? 'absent' : 'present',
+        fileUploadsService: fileUploads === undefined ? 'absent' : 'present',
+        ...(connection === undefined ? {} : { connectionShape: checkFetchRouteShape(connection) }),
+        ...(fetchRoute === undefined ? {} : { fetchRoute }),
+      }
+      return cached
+    }
+  }
   // The plugin bridge's zenRemote service (PB-1), provided on BOTH roles
   // before any role branch: a plugin that wants its panel data forwarded in
   // remote sessions declares that against THIS process whichever role it
@@ -766,23 +817,13 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       // the registry dsh-client-ui-deliverables' changes routes register
       // into), so a synthetic Request reaches the serving functions directly:
       // no loopback HTTP, no login state. A composition without the service
-      // answers the relay route 501 instead.
-      const getApiFetch = (): ((request: Request) => Promise<Response>) | undefined => {
-        const connection = relayCtx.reflect.get('connection') as
-          | { createSharedFetchHandler?: (channel: string) => { fetch?: (request: Request) => Promise<Response> } }
-          | undefined
-        const handler = connection?.createSharedFetchHandler?.('/api')
-        const fetch = handler?.fetch
-        return typeof fetch === 'function' ? (request) => fetch.call(handler, request) : undefined
-      }
-      // The server's interface fingerprints (T42): recomputed at EVERY
-      // handshake, deliberately uncached — the typert loader registers
-      // package by package asynchronously, so a client that auto-reconnects
-      // right after a server restart would otherwise handshake a half-empty
-      // registry and pin those throwaway values for the row's lifetime.
-      // ~7 ms per computation against a full registry; a failed compute
-      // lands as the empty map inside the relay handler's own guard.
+      // answers the relay route 501 instead. DSH 0.2.1-rc.3: the handler's
+      // fetch takes the requesting Peer as a second argument and refuses
+      // everything but the owner (a missing peer there throws TypeError,
+      // surfacing as a 502 on every relayed /api call) — the dispatcher
+      // forwards the cached owner Peer below; pre-rc.3 hosts ignore it.
       const relayPeer = createOwnerPeerSource(() => relayCtx.reflect.get('connection'))
+      const getApiFetch = createSharedApiFetchGetter(() => relayCtx.reflect.get('connection'), relayPeer)
       relayCtx.effect(() => {
         // The plugin bridge's loopback facts (PB-3), both read PER REQUEST
         // through the reflection layer: the web server may have restarted on
@@ -830,6 +871,14 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
             // snapshotted from the resolveConfig call above.
             serverName: () => resolveConfig(config, readFileConfig(), process.env).values.serverName,
             dshVersion: resolveDshVersion(),
+            // The server's interface fingerprints (T42): recomputed at EVERY
+            // handshake, deliberately uncached — the typert loader registers
+            // package by package asynchronously, so a client that
+            // auto-reconnects right after a server restart would otherwise
+            // handshake a half-empty registry and pin those throwaway values
+            // for the row's lifetime. ~7 ms per computation against a full
+            // registry; a failed compute lands as the empty map inside the
+            // relay handler's own guard.
             fingerprints: () => computeFingerprints(relayCtx),
             // PB-2: the plugin bridge table, rebuilt FRESH at every handshake
             // from the PB-1 registry and the row's consent map — both live:
@@ -909,6 +958,7 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           admit: (req) => clientCtx.connection.admit(req),
           getRowConfig: () => config,
           remoteStatusOnly: true,
+          getServiceProbe: uploadServiceProbe(clientCtx),
         }),
       }), 'dsh-zen-remote: client routes (host)')
     })
@@ -1121,7 +1171,9 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
       }
       return undefined
     }
+    fetchRouteDiagnosticsRef = fetchRouteDiagnostics
     ctx.inject(['connection', 'fileUploads'], (connectionCtx) => {
+      fetchRouteInjectSeen = true
       const logWarn = (...args: Parameters<Context['logger']['warn']>): void => { ctx.logger?.warn(...args) }
       const logInfo = (...args: Parameters<Context['logger']['info']>): void => { ctx.logger?.info(...args) }
       const proxy = (connectionCtx as Context & { connection?: unknown }).connection
@@ -1232,6 +1284,7 @@ export function apply(ctx: Context, config: MobileNavConfig = {}): void {
           getRelayClient: () => relayClient,
           getIntercept: interceptDiagnostics,
           getFetchRouteIntercept: fetchRouteDiagnostics,
+          getServiceProbe: uploadServiceProbe(clientCtx),
           getPluginRouteIntercept: pluginRouteDiagnostics,
           getPluginBridgeStatus: pluginBridgeStatus,
           onCurrentSession,

package/src/intercept.ts

@@ -183,6 +183,14 @@ export const CLIENT_METHOD_FIELDS: Readonly<Record<string, readonly SessionField
   'workspaceFiles/read': ['workspaceFileScopeId'],
   'workspaceFiles/readBytes': ['workspaceFileScopeId'],
   'workspaceFiles/stat': ['workspaceFileScopeId'],
+  // Office document preview (2.2.6) — client side of relay-access.ts's entry:
+  // `render` is located by the SAME `workspaceFileScopeId` lookup (the session
+  // id). It MUST stay identical to the server table
+  // (test/intercept.test.cjs pins the equality), otherwise a produced
+  // Word/Excel/PPT preview refuses locally with `remote-unsupported` before
+  // the relay is ever asked. `generation` stays unregistered: no virtual id
+  // rides it, so it answers locally (see the server table's note).
+  'officeToPdf/render': ['workspaceFileScopeId'],
   // terminal (T41a) — opens SERVER-side by explicit user request (SPEC story
   // 45); the boundary is the standing one (shared session + paired desktop
   // client), no extra switch. The terminal and attachment ids in these calls
@@ -319,6 +327,11 @@ export const REMOTE_READ_METHODS: ReadonlySet<string> = new Set([
   'workspaceFiles/read',
   'workspaceFiles/readBytes',
   'workspaceFiles/stat',
+  // officeToPdf (2.2.6): a pure read — it converts one already-readable file
+  // into PDF bytes on the server (writing only its own scratch space, like
+  // any preview). Offline it answers `remote-offline`, never the write
+  // message.
+  'officeToPdf/render',
   'terminal/environment',
   'terminal/shells',
   'terminal/list',

package/src/invoke-binary.ts

@@ -17,8 +17,14 @@
 export const BINARY_MARKER = '$zr-u8'
 
 /** 结果里带二进制的方法（`namespace/method`）。请求侧参数不带二进制
- * （readBytes 的参数是 scope/paths），故只有结果方向需要标记。 */
-export const INVOKE_BINARY_RESULT_METHODS: ReadonlySet<string> = new Set(['workspaceFiles/readBytes'])
+ * （readBytes 的参数是 scope/paths），故只有结果方向需要标记。
+ * `officeToPdf/render`（2.2.6）返回的 `data` 是整份 PDF 字节：同一个
+ * JSON 通道会把 typed array 压扁，客户端严格编解码当场拒绝——登记进来
+ * 后服务端按同一标记写出、客户端按同一标记还原。 */
+export const INVOKE_BINARY_RESULT_METHODS: ReadonlySet<string> = new Set([
+  'workspaceFiles/readBytes',
+  'officeToPdf/render',
+])
 
 /** 深度上限：与其余 walker（share-store 祖先链、会话引用扫描）一致。 */
 const MAX_DEPTH = 16

package/src/owner-peer.ts

@@ -79,3 +79,35 @@ export function withPeer<T extends object>(request: T, getPeer: (() => unknown)
   const peer = getPeer?.()
   return peer === undefined ? request : { ...request, peer }
 }
+
+/**
+ * Build the `/api` shared-fetch dispatcher reader for the relay server.
+ * DSH 0.2.1-rc.3's `HostConnectionService.createSharedFetchHandler('/api').fetch(request, peer)`
+ * checks `peer.principal.kind !== 'owner'` directly (returning 403 or throwing
+ * TypeError when `peer` is undefined), so the dispatcher forwards the owner
+ * Peer from `getPeer()` as the second argument. Pre-rc.3 hosts ignore the
+ * extra argument.
+ */
+export function createSharedApiFetchGetter(
+  getConnection: () => unknown,
+  getPeer: () => unknown = createOwnerPeerSource(getConnection),
+): () => ((request: Request) => Promise<Response>) | undefined {
+  return () => {
+    let connection:
+      | {
+          createSharedFetchHandler?: (channel: string) => {
+            fetch?: (request: Request, peer?: unknown) => Promise<Response>
+          }
+        }
+      | undefined
+    try {
+      const value = getConnection()
+      connection = value !== null && typeof value === 'object' ? (value as typeof connection) : undefined
+    } catch {
+      connection = undefined
+    }
+    const handler = connection?.createSharedFetchHandler?.('/api')
+    const fetch = handler?.fetch
+    return typeof fetch === 'function' ? (request) => fetch.call(handler, request, getPeer()) : undefined
+  }
+}

package/src/plugin-adapter-core.ts

@@ -163,13 +163,13 @@ export interface NormalizedAdapter {
 const PLUGIN_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u
 const MAX_ROUTES = 64
 
-/** The body cap an ADAPTER route may declare: 100 MiB — the relay's own
+/** The body cap an ADAPTER route may declare: 500 MiB — the relay's own
  * upload budget (lib/relay-server.js `MAX_UPLOAD_BYTES`), which the
  * better-sidebar upload route rides. Wider than the cooperative
  * declaration's 64 MiB because raw media uploads are exactly what an
  * adapter exists to carry; test/adapter-better-sidebar.test.cjs pins the
  * two numbers together. */
-export const MAX_ADAPTER_BODY_BYTES = 100 * 1024 * 1024
+export const MAX_ADAPTER_BODY_BYTES = 500 * 1024 * 1024
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)

package/src/relay-access.ts

@@ -190,8 +190,7 @@ interface RelayMethod {
  * account management, settings, credentials, the methods located by other
  * ids (`schedule/update|delete|history`, `goals/create|complete`,
  * `fileUploads/list|resolve`, `agentPresets/list|read`,
- * `permissionPresets/*`, `officeToPdf/*`, `dynamicCordisRunner/*`) — is
- * refused by default.
+ * `permissionPresets/*`, `dynamicCordisRunner/*`) — is refused by default.
  *
  * T31 registered the five session-creating / agent-scoped calls after
  * verifying their ownership story (see the field notes above): creations
@@ -263,6 +262,29 @@ const RELAY_METHODS: Record<string, RelayMethod> = {
   'workspaceFiles/read': { fields: ['workspaceFileScopeId'] },
   'workspaceFiles/readBytes': { fields: ['workspaceFileScopeId'] },
   'workspaceFiles/stat': { fields: ['workspaceFileScopeId'] },
+  // Office document preview (2.2.6, remote Word/Excel/PPT). The document
+  // preview's Office renderer does NOT convert on the client: it asks the
+  // HOST's LibreOffice to turn doc/docx/xls/xlsx/ppt/pptx into PDF
+  // (RT dsh-client-ui-sidebar-documentpreview lib/client.js ~6101: the
+  // office face is built from `ctx.remote.officeToPdf` +
+  // `ctx.remote.workspaceFiles`), so a remote session without this entry
+  // fails the preview with `remote-unsupported` — the exact
+  // 「此功能暂不支持远程会话」 a client sees when it opens a produced Word
+  // file. `render` carries the SAME `workspaceFileScope` lookup as the
+  // workspaceFiles group (RT dsh-office-to-pdf lib/typert.remote-client.js:
+  // parameter 0 name `workspaceFileScope`, wire `workspaceFileScopeId`,
+  // typeSymbol SessionId) and reads under the same permissive rule
+  // (absolute paths anywhere the server process can read) — the trust
+  // premise accepted above for previews applies unchanged.
+  // `officeToPdf/generation` (zero-arity, RT same file `parameters: []`)
+  // stays UNREGISTERED on purpose: a field-less call carries no virtual id,
+  // so the client's interception never routes it here — it answers from the
+  // LOCAL renderer, which is all its cache-invalidation use needs.
+  // The RESULT of render carries `data: Uint8Array` (complete PDF bytes), so
+  // the method is ALSO registered in invoke-binary.ts's
+  // INVOKE_BINARY_RESULT_METHODS — without that marker the JSON channel
+  // flattens the typed array and the client's strict codec rejects it.
+  'officeToPdf/render': { fields: ['workspaceFileScopeId'] },
   // terminal (T41a) — opens SERVER-side by explicit user request (SPEC story
   // 45). What the client gets is a shell running AS THE SERVER USER, WITHOUT
   // the agent sandbox or approval restrictions (RT dsh-api-terminal-controller

package/src/relay-client.ts

@@ -76,7 +76,7 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 15_000
 
 /**
  * The invoke round-trip budget (T31-fix): the configured request timeout
- * plus 2 s per MiB of request body, capped at five minutes. The large
+ * plus 2 s per MiB of request body, capped at fifteen minutes. The large
  * bodies are the prompt routes' INLINE images — `session/prompt` /
  * `subagents/prompt` content blocks carry base64 `image` data, one image up
  * to 20 MiB by default (`maxImageBytes`, dsh-attachment-local) or ~27 MiB
@@ -84,7 +84,7 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 15_000
  * base seconds. The cap never lands below the configured base timeout.
  */
 const INVOKE_TIMEOUT_PER_MIB_MS = 2_000
-const INVOKE_TIMEOUT_CAP_MS = 300_000
+const INVOKE_TIMEOUT_CAP_MS = 900_000
 
 /**
  * How often an ONLINE client re-runs the handshake purely to refresh the two

package/src/relay-server.ts

@@ -73,7 +73,7 @@ const MAX_BODY_BYTES = 1024 * 1024
  * host stores the stream verbatim (`saveFileStreamVerbatim` →
  * `publishImmutableObjectStream`, RT dsh-attachment-local lib/index.js
  * ~699-716; the 20 MiB `maxImageBytes` there covers INLINE images only), so
- * there is no host number to mirror and this relay picks its own: 100 MiB
+ * there is no host number to mirror and this relay picks its own: 500 MiB
  * per upload, checked first against `Content-Length` (refused before a byte
  * moves) and then counted while the stream is pumped (a chunked body has no
  * length header — the sub-client's undici forbids hand-set length headers,
@@ -82,13 +82,16 @@ const MAX_BODY_BYTES = 1024 * 1024
  * answer is 413 `payload-too-large`.
  *
  * SLOW-LINK BOUND (T51-fix, for the docs): a single legitimate upload is
- * also bounded in TIME — the host's HTTP server keeps its default 300 s
- * request deadline, and the sub-client's own round-trip budget caps at the
- * same 300 s (relay-client.ts, the T31-fix rule) — so a 100 MiB body needs
- * roughly 2.8 Mbps sustained end to end; slower links fail the call (the
- * client-side refusal keeps the connection state) rather than hanging.
+ * also bounded in TIME. The sub-client's own round-trip budget now caps at
+ * 15 minutes (relay-client.ts, the T31-fix rule), but the HOST's HTTP server
+ * keeps Node's default 300 s request deadline — that is the binding limit:
+ * a 500 MiB body needs roughly 14 Mbps sustained end to end, and a slower
+ * link fails the call (the client-side refusal keeps the connection state)
+ * rather than hanging. Raising the cap past what that deadline can carry
+ * would only move the failure, so 500 MiB is the honest ceiling for the
+ * current transport.
  */
-export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024
+export const MAX_UPLOAD_BYTES = 500 * 1024 * 1024
 
 /** The `/api` route the upload channel dispatches into, verbatim from the
  * host's own registration (RT dsh-client-file-upload lib/index.js:73). */
@@ -286,7 +289,7 @@ export interface RelayHandlerOptions {
    * defaults to 5000. Tests inject a small value. */
   endDrainTimeoutMs?: number
   /** The binary upload channel's byte cap (T51); defaults to
-   * {@link MAX_UPLOAD_BYTES} (100 MiB). Tests inject a small value so the
+   * {@link MAX_UPLOAD_BYTES} (500 MiB). Tests inject a small value so the
    * Content-Length and streaming-count refusals stay cheap to drive. */
   uploadCapBytes?: number
   /** How long an upload refusal's tail drain may run before the socket is
@@ -424,6 +427,100 @@ function headerValue(req: IncomingMessage, name: string): string | undefined {
   return typeof value === 'string' ? value : undefined
 }
 
+/** The streaming upload pump behind `v1/upload`: the client's chunks are
+ * re-emitted into a
+ * synthetic body verbatim, counted on the way through, with real
+ * backpressure (the socket pauses whenever the consumer is not pulling).
+ * Past the cap the pump errors — the consumer's reader throws mid-write —
+ * and the route answers its own 413 before draining the tail. Returned as
+ * accessors so the route can judge the cap AFTER the consumer settles. */
+interface PumpedUploadBody {
+  body: ReadableStream<Uint8Array>
+  received: () => number
+  tooLarge: () => boolean
+  /** Detach the socket listeners once the route is done with the body. */
+  detach: () => void
+}
+
+function pumpUploadBody(
+  req: IncomingMessage,
+  res: ServerResponse,
+  cap: number,
+  hangUp: AbortController,
+): PumpedUploadBody {
+  let received = 0
+  let tooLarge = false
+  const onClientGone = (): void => {
+    if (!res.writableEnded) hangUp.abort()
+  }
+  res.on('close', onClientGone)
+  const body = new ReadableStream<Uint8Array>({
+    start: (controller) => {
+      req.pause()
+      req.on('data', (chunk: Buffer) => {
+        if (tooLarge) return
+        received += chunk.byteLength
+        if (received > cap) {
+          tooLarge = true
+          req.pause()
+          hangUp.abort()
+          try {
+            controller.error(new Error('payload-too-large'))
+          } catch {
+            // The consumer may have cancelled first.
+          }
+          return
+        }
+        try {
+          controller.enqueue(new Uint8Array(chunk))
+        } catch {
+          req.destroy()
+          return
+        }
+        if (controller.desiredSize !== null && controller.desiredSize <= 0) req.pause()
+      })
+      req.on('end', () => {
+        if (tooLarge) return
+        try {
+          controller.close()
+        } catch {
+          // Already errored by the consumer's cancel.
+        }
+      })
+      req.on('error', () => {
+        if (tooLarge) return
+        try {
+          controller.error(new Error('upload stream failed'))
+        } catch {
+          // Already errored.
+        }
+      })
+      req.on('close', () => {
+        if (tooLarge) return
+        try {
+          controller.close()
+        } catch {
+          // A hang-up destroy after a clean end — nothing to close.
+        }
+      })
+    },
+    pull: () => {
+      req.resume()
+    },
+    cancel: () => {
+      req.pause()
+    },
+  })
+  return {
+    body,
+    received: () => received,
+    tooLarge: () => tooLarge,
+    detach: () => {
+      res.off('close', onClientGone)
+    },
+  }
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
@@ -2102,83 +2199,10 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         return
       }
       // A hang-up cancels the forward mid-stream, like invoke's — and the
-      // cap pump below aborts the SAME controller when it trips, so an
-      // oversized upload dies at the host side the moment it is judged.
+      // cap pump (pumpUploadBody) aborts the SAME controller when it trips,
+      // so an oversized upload dies at the host side the moment it is judged.
       const hangUp = new AbortController()
-      const onClientGone = (): void => {
-        if (!res.writableEnded) hangUp.abort()
-      }
-      res.on('close', onClientGone)
-      // The counting pump: the client's chunks are re-emitted into the
-      // synthetic body verbatim, counted on the way through, with real
-      // backpressure (the socket pauses whenever the host handler is not
-      // pulling). Past the cap the pump errors — the host's reader throws
-      // out of `requestBodyChunks` and its upload dies mid-write — and the
-      // answer below is the relay's own 413 (written before the tail drain),
-      // never the host's internal failure envelope. `tooLarge` also detaches
-      // the pump from the socket: the tail belongs to drainUpload's bound,
-      // which continues from the pump's own count.
-      let received = 0
-      let tooLarge = false
-      const body = new ReadableStream<Uint8Array>({
-        start: (controller) => {
-          req.pause()
-          req.on('data', (chunk: Buffer) => {
-            if (tooLarge) return
-            received += chunk.byteLength
-            if (received > uploadCapBytes) {
-              tooLarge = true
-              req.pause()
-              hangUp.abort()
-              try {
-                controller.error(new Error('payload-too-large'))
-              } catch {
-                // The host consumer may have cancelled first.
-              }
-              return
-            }
-            try {
-              controller.enqueue(new Uint8Array(chunk))
-            } catch {
-              req.destroy()
-              return
-            }
-            if (controller.desiredSize !== null && controller.desiredSize <= 0) req.pause()
-          })
-          req.on('end', () => {
-            if (tooLarge) return
-            try {
-              controller.close()
-            } catch {
-              // Already errored by the consumer's cancel.
-            }
-          })
-          req.on('error', () => {
-            if (tooLarge) return
-            try {
-              controller.error(new Error('upload stream failed'))
-            } catch {
-              // Already errored.
-            }
-          })
-          req.on('close', () => {
-            if (tooLarge) return
-            try {
-              controller.close()
-            } catch {
-              // A hang-up destroy after a clean end — nothing to close.
-            }
-          })
-        },
-        pull: () => {
-          req.resume()
-        },
-        cancel: () => {
-          // The host consumer stopped reading (its own error path): stop
-          // pulling from the client too — the drain below finishes the wire.
-          req.pause()
-        },
-      })
+      const pump = pumpUploadBody(req, res, uploadCapBytes, hangUp)
       let request: Request
       try {
         // The URL is composed from the DECISION's normalized query alone,
@@ -2188,7 +2212,7 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         const init: RequestInit = {
           method: 'POST',
           headers: { 'content-type': 'application/octet-stream' },
-          body,
+          body: pump.body,
           signal: hangUp.signal,
         }
         // `duplex: 'half'` is mandatory for a streaming request body; the
@@ -2215,10 +2239,10 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         // wire, and the sub-client reconstructs the exact Response its UI
         // would have seen locally.
         const bodyText = await upstream.text()
-        if (tooLarge) {
+        if (pump.tooLarge()) {
           res.setHeader('Connection', 'close')
           responseJson(res, 413, PAYLOAD_TOO_LARGE)
-          await drainUpload(req, received, drainDeadlineMs)
+          await drainUpload(req, pump.received(), drainDeadlineMs)
           return
         }
         const contentType = upstream.headers.get('content-type') ?? undefined
@@ -2232,15 +2256,15 @@ export function createRelayHandler(options: RelayHandlerOptions): RelayHandler {
         // cap verdict outranks it: the abort the pump sent INTO the dispatch
         // surfaces here as a throw, and the client still gets its 413
         // (before the tail drain, like every oversize answer).
-        if (tooLarge) {
+        if (pump.tooLarge()) {
           res.setHeader('Connection', 'close')
           responseJson(res, 413, PAYLOAD_TOO_LARGE)
-          await drainUpload(req, received, drainDeadlineMs)
+          await drainUpload(req, pump.received(), drainDeadlineMs)
           return
         }
         responseJson(res, 502, { ok: false, error: { code: 'internal' } })
       } finally {
-        res.off('close', onClientGone)
+        pump.detach()
         // The upload is over — answered, refused mid-flight, or its client
         // gone: the budget slot goes back (T51-fix).
         const remaining = (uploadsByDevice.get(device) ?? 1) - 1