feat(browser): bound tunnel route resources

Author: Jinwoo-H

config/reliability-gates.jsonc

@@ -2354,12 +2354,12 @@
       "providers": ["local", "remote-runtime", "ssh", "wsl"],
       "coveredPlatforms": ["macos"],
       "coveredProviders": ["remote-runtime"],
-      "coverageNotes": "Deterministic protocol, registry, injected-socket, and loopback-listener tests cover strict framing, remote-DNS targets, exact destination-write and source-consumption credit, bounded receive bytes and chunks, authority epochs, exact host selection, one host per authenticated connection, four hosts per paired device, long-poll metering and disconnect abort, monotonic host/page/route generations without page tombstones, connection-owned cleanup, exact client revocation, stale and replaced fences, retired stream IDs, half-close and close ordering, SOCKS CONNECT, bind/close races, listener wildcard normalization, unsupported commands, unavailable routes, and raw/terminal binary-handler isolation. Explicitly injected browser-host and paired-runtime tunnel methods lease one exact host, then carry SOCKS and HTTP bytes over a dedicated E2EE socket to the fenced native execution-host revision and prove route close destroys the destination socket. Both methods and capabilities remain disabled in production. SSH and WSL providers remain uncovered.",
+      "coverageNotes": "Deterministic protocol, registry, injected-socket, and loopback-listener tests cover strict framing, remote-DNS targets, exact destination-write and source-consumption credit, at most 16 pending opens, 128 admitted opens per 10-second monotonic window, an 8 MiB aggregate application-buffer ledger across both traffic directions, bounded per-stream receive bytes and chunks, authority epochs, exact host selection, one host per authenticated connection, four hosts per paired device, long-poll metering and disconnect abort, monotonic host/page/route generations without page tombstones, connection-owned cleanup, exact client revocation, stale and replaced fences, retired stream IDs, half-close and close ordering, SOCKS CONNECT, bind/close races, listener wildcard normalization, unsupported commands, unavailable routes, and raw/terminal binary-handler isolation. Explicitly injected browser-host and paired-runtime tunnel methods lease one exact host, then carry SOCKS and HTTP bytes over a dedicated E2EE socket to the fenced native execution-host revision and prove route close destroys the destination socket. Both methods and capabilities remain disabled in production. Encrypted transport buffers, browser-host/process ledgers, SSH, and WSL remain uncovered.",
       "motivatingLinks": [
         "https://linear.app/stably/issue/STA-4150/refactor-remote-browser-to-client-hosted-electron-webviews"
       ],
-      "invariant": "A client-hosted browser network route exists only for an exact live server-owned browser-host lease, authority epoch, host generation, paired identity, execution-host revision, and server-owned route generation. Host selection never chooses arbitrarily, stale cleanup cannot remove a replacement, destination names remain unresolved until the execution host, credit returns only after writes settle, and route loss never falls back to desktop DNS or sockets. The local SOCKS endpoint accepts only loopback CONNECT and rejects unsupported commands.",
-      "oracle": "Attach two browser hosts and require unqualified selection to fail ambiguous while exact selection succeeds. Reject a second identity on one connection and a fifth identity for one paired device, release one exact lease, then admit its replacement without starving another device. Saturate the browser-host long-poll sub-cap, require an ordinary wait to remain admitted, close the socket, and prove both counters and handlers release. Replace one same-device connection, require the old subscription and route to fence, then prove late old cleanup leaves the new generation live. Retire a closed page placement by exact token, reject delayed cleanup against a replacement and server placement, and require its reused ID to receive a higher global generation without retaining a tombstone. Reject missing, stale, wrong-device, wrong-epoch, and wrong-execution-revision tunnel requests before binary registration. Drive the accepted lease through a real paired E2EE SOCKS-to-HTTP journey, then exercise exact frame, credit, half-close, stale-stream, remote-DNS, unsupported-command, offline, and teardown assertions.",
+      "invariant": "A client-hosted browser network route exists only for an exact live server-owned browser-host lease, authority epoch, host generation, paired identity, execution-host revision, and server-owned route generation. Host selection never chooses arbitrarily, stale cleanup cannot remove a replacement, destination names remain unresolved until the execution host, credit returns only after writes settle, and route loss never falls back to desktop DNS or sockets. Pending opens, admitted open rate, and session-retained application bytes remain bounded with exact release on settlement and retirement. The local SOCKS endpoint accepts only loopback CONNECT and rejects unsupported commands.",
+      "oracle": "Attach two browser hosts and require unqualified selection to fail ambiguous while exact selection succeeds. Reject a second identity on one connection and a fifth identity for one paired device, release one exact lease, then admit its replacement without starving another device. Saturate the browser-host long-poll sub-cap, require an ordinary wait to remain admitted, close the socket, and prove both counters and handlers release. Replace one same-device connection, require the old subscription and route to fence, then prove late old cleanup leaves the new generation live. Retire a closed page placement by exact token, reject delayed cleanup against a replacement and server placement, and require its reused ID to receive a higher global generation without retaining a tombstone. Admit 16 pending destination opens and reject the seventeenth until one connects; admit 128 opens in one monotonic 10-second window and reject the 129th until the window expires. Fill 8 MiB across destination-to-client queues and separately across unsettled client-to-destination writes, release one exact retired stream, admit one replacement, and require the next byte claim to close the route without stale-callback or reentrant-close underflow. Reject missing, stale, wrong-device, wrong-epoch, and wrong-execution-revision tunnel requests before binary registration. Drive the accepted lease through a real paired E2EE SOCKS-to-HTTP journey, then exercise exact frame, credit, half-close, stale-stream, remote-DNS, unsupported-command, offline, and teardown assertions.",
       "commands": [
         "pnpm exec vitest run --config config/vitest.config.ts src/shared/browser-network-capabilities.test.ts src/shared/browser-network-tunnel-protocol.test.ts src/main/browser/browser-network-tunnel-session.test.ts src/main/browser/remote-browser-socks-server.test.ts",
         "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/browser-network-tunnel-client.test.ts src/main/browser/paired-runtime-browser-network-route.test.ts src/main/runtime/runtime-binary-message-router.test.ts src/main/runtime/rpc/methods/browser-network-tunnel.test.ts src/main/runtime/browser-network-tunnel-paired-runtime.integration.test.ts",
@@ -2423,7 +2423,10 @@
           "file": "src/main/browser/browser-network-tunnel-session.test.ts",
           "assertions": [
             "destination writes replenish client credit only after settlement",
-            "stale generations and reused stream IDs cannot replace the current destination"
+            "stale generations and reused stream IDs cannot replace the current destination",
+            "pending opens and admitted open rate remain bounded and recover only after exact release or window expiry",
+            "both traffic directions share an 8 MiB application-retention ledger with exact settlement, retirement, stale-callback, and reentrant-close release",
+            "unsettled client-to-destination writes retain at most 256 chunks per stream independently of byte credit"
           ]
         },
         {
@@ -2483,6 +2486,15 @@
         }
       ],
       "evidenceRuns": [
+        {
+          "date": "2026-08-14",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/shared/browser-client-host-protocol.test.ts src/main/runtime/browser-host-lease-registry.test.ts src/main/runtime/runtime-rpc-browser-host-admission.test.ts src/main/runtime/rpc/methods/browser-client-host.test.ts src/main/runtime/rpc/methods/browser-network-tunnel.test.ts src/main/browser/paired-runtime-browser-host-lease.test.ts src/main/browser/paired-runtime-browser-network-route.test.ts src/main/runtime/browser-network-tunnel-paired-runtime.integration.test.ts src/main/browser/browser-network-tunnel-client.test.ts src/main/browser/browser-network-tunnel-session.test.ts src/main/browser/remote-browser-socks-server.test.ts",
+          "result": "passed",
+          "durationSeconds": 6.9,
+          "summary": "Eleven files passed 73 admission, lease, route-generation, bidirectional retained-byte/chunk, pending-open/rate, exact-release, SOCKS, and real paired E2EE tests; the full runtime-RPC suite separately passed 1,347 tests with one skip."
+        },
         {
           "date": "2026-08-14",
           "runner": "local",
@@ -2530,14 +2542,14 @@
       },
       "redGreenEvidence": {
         "status": "partial",
-        "evidence": "The protocol and tunnel-session oracles fail on origin/main 3246b73add because the modules do not exist, then pass on the candidate. The lease registry and control-client suites were recorded red at missing modules before implementation. The unchanged tunnel authorization oracle was behaviorally red because an authenticated socket could self-assert its paired device ID and received ready generation 7 without a lease; it is green after server-owned lease and route fencing. On c9a41abf24, the unchanged admission oracle failed three ways: a second identity on one connection and a fifth identity for one paired device were both admitted, and closed page placement had no retirement API. All three pass after bounded admission and tombstone-free global page generations. The real paired journey failed at the missing network.browserTunnel method before explicit test injection, then passed with an exact control lease while both production registries remained closed. Full mutation/revert evidence remains to be collected before promotion."
+        "evidence": "The protocol and tunnel-session oracles fail on origin/main 3246b73add because the modules do not exist, then pass on the candidate. The lease registry and control-client suites were recorded red at missing modules before implementation. The unchanged tunnel authorization oracle was behaviorally red because an authenticated socket could self-assert its paired device ID and received ready generation 7 without a lease; it is green after server-owned lease and route fencing. On c9a41abf24, the unchanged admission oracle failed three ways: a second identity on one connection and a fifth identity for one paired device were both admitted, and closed page placement had no retirement API. All three pass after bounded admission and tombstone-free global page generations. On parent 392d13be9f, the deterministic resource oracle admitted 17 pending opens, admitted a 129th open inside 10 seconds, and retained more than 8 MiB across one route; all three failed assertions pass on the candidate, which also covers unsettled writes and reentrant exact release. The real paired journey failed at the missing network.browserTunnel method before explicit test injection, then passed with an exact control lease while both production registries remained closed. Full mutation/revert evidence remains to be collected before promotion."
       },
       "performanceBudget": {
         "required": true,
-        "evidence": "Data frames, send credit, pending bytes and chunk counts in both directions, streams, SOCKS handshake and pipelined application bytes are bounded. One authenticated connection retains at most one browser host and one paired device at most four, with exact release restoring admission. Permanent browser-host polls use at most one quarter of the shared long-poll slots, and real injected dispatch proves an ordinary wait remains admitted and socket close releases both classes. Credit returns only after the execution-host or browser-facing socket write settles, and the injected transport must explicitly accept each frame. Pending-open/rate admission, aggregate route/browser-host/process byte ledgers, and drain-aware fair scheduling remain required before live tunnel advertisement."
+        "evidence": "Data frames, send credit, pending bytes and chunk counts in both directions, streams, SOCKS handshake, and pipelined application bytes are bounded. Each route admits at most 16 pending opens, 128 opens per monotonic 10-second window, and 8 MiB of session-owned queued or unsettled application bytes with exact settlement and retirement release. One authenticated connection retains at most one browser host and one paired device at most four, with exact release restoring admission. Permanent browser-host polls use at most one quarter of the shared long-poll slots, and real injected dispatch proves an ordinary wait remains admitted and socket close releases both classes. Credit returns only after the execution-host or browser-facing socket write settles, and the injected transport must explicitly accept each frame. Encrypted WebSocket/native buffers, aggregate browser-host/process ledgers, and drain-aware fair scheduling remain required before live tunnel advertisement."
       },
       "promotionCriteria": [
-        "Add bounded pending-open admission and open-rate limits plus aggregate route, browser-host, and process memory ledgers with runtime-wide fair scheduling.",
+        "Complete aggregate accounting across encrypted transport/native buffers, browser hosts, and the process with runtime-wide fair scheduling.",
         "Approve all same-host local processes and users as inside the desktop trust boundary or replace SOCKS no-auth with Chromium-compatible process isolation.",
         "Add old/new peer coverage to the dedicated paired-runtime binary tunnel journey.",
         "Add SSH2, system SSH, WSL, Linux, and physical Windows evidence.",
@@ -2546,7 +2558,7 @@
       "knownGaps": [
         "No runtime capability is advertised, the paired tunnel method is not registered in production, and no Electron webview selects it yet.",
         "The token-safe page-retirement API has no production lifecycle caller until client placement activates.",
-        "Pending-open and open-rate admission plus aggregate encrypted-WebSocket and destination-buffer accounting are not implemented.",
+        "Session-owned application buffers are bounded, but encrypted WebSocket/native buffers and aggregate browser-host/process accounting are not implemented.",
         "The loopback SOCKS endpoint uses Chromium-compatible no-auth and is not safe to activate until its desktop trust boundary is approved or isolated.",
         "SSH, WSL, browserless serve, Electron proxy policy, UDP denial, and desktop DNS/socket capture are not exercised."
       ],

src/main/browser/browser-network-tunnel-destination-flow.ts

@@ -14,12 +14,25 @@ type BrowserNetworkTunnelDestinationFlowActions = {
   sendData: (bytes: Uint8Array<ArrayBufferLike>) => boolean
   sendHalfClose: () => void
   finalizeClose: () => void
+  releaseRetainedBytes: (bytes: number) => void
+}
+
+export function halfCloseBrowserNetworkDestination(
+  stream: BrowserNetworkTunnelStream
+): string | null {
+  if (!stream.connected || stream.clientEnded) {
+    return 'invalid_client_half_close'
+  }
+  stream.clientEnded = true
+  stream.socket.end()
+  return null
 }
 
 export function writeBrowserNetworkDestination(
   stream: BrowserNetworkTunnelStream,
   payload: Uint8Array<ArrayBufferLike>,
-  onSettled: (bytes: number) => void
+  onSettled: (bytes: number) => void,
+  claimRetainedBytes: (bytes: number) => (() => void) | null
 ): string | null {
   if (!stream.connected || stream.clientEnded) {
     return 'invalid_client_data'
@@ -30,9 +43,31 @@ export function writeBrowserNetworkDestination(
   if (payload.byteLength === 0) {
     return null
   }
+  if (
+    stream.pendingDestinationWriteReleases.size >= BROWSER_NETWORK_TUNNEL_MAX_PENDING_SOCKET_CHUNKS
+  ) {
+    return 'destination_write_chunk_overflow'
+  }
+  const releaseClaim = claimRetainedBytes(payload.byteLength)
+  if (!releaseClaim) {
+    return 'route_buffer_overflow'
+  }
   stream.receiveCredit -= payload.byteLength
   const bytes = payload.slice()
-  stream.socket.write(bytes, () => onSettled(bytes.byteLength))
+  let retained = true
+  const release = (): void => {
+    if (!retained) {
+      return
+    }
+    retained = false
+    stream.pendingDestinationWriteReleases.delete(release)
+    releaseClaim()
+  }
+  stream.pendingDestinationWriteReleases.add(release)
+  stream.socket.write(bytes, () => {
+    release()
+    onSettled(bytes.byteLength)
+  })
   return null
 }
 
@@ -84,8 +119,12 @@ export function flushBrowserNetworkDestination(
     if (!actions.sendData(next.subarray(0, length))) {
       return
     }
+    if (!actions.isCurrent()) {
+      return
+    }
     stream.sendCredit -= length
     stream.pendingToClientBytes -= length
+    actions.releaseRetainedBytes(length)
     if (length === next.byteLength) {
       stream.pendingToClient.shift()
     } else {

src/main/browser/browser-network-tunnel-frame-sender.ts

@@ -1,6 +1,6 @@
 import {
+  BrowserNetworkTunnelOpcode,
   encodeBrowserNetworkTunnelFrame,
-  type BrowserNetworkTunnelOpcode,
   type BrowserNetworkTunnelFrame
 } from '../../shared/browser-network-tunnel-protocol'
 import type { BrowserNetworkTunnelSessionOptions } from './browser-network-tunnel-stream-state'
@@ -43,4 +43,8 @@ export class BrowserNetworkTunnelFrameSender {
     }
     return accepted
   }
+
+  sendError(streamId: number, code: string): boolean {
+    return this.send(BrowserNetworkTunnelOpcode.Error, streamId, new TextEncoder().encode(code))
+  }
 }