feat(browser): fence client page placements

Author: Jinwoo-H

config/reliability-gates.jsonc

@@ -2584,6 +2584,7 @@
         "capability-gated native and SSH execution-host adapters",
         "main-owned loopback SOCKS5 route",
         "runtime-owned browser-host lease and placement authority",
+        "exact live client-page placement admission",
         "dedicated paired-runtime E2EE tunnel subscription"
       ],
       "platforms": ["macos", "linux", "windows"],
@@ -2594,9 +2595,10 @@
       "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 or SSH provider authority, and server-owned route generation. Non-native descriptors require explicit capability negotiation and an exact runtime-minted lease-bound execution-host grant. 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. A main-owned local listener remains stable across upstream transport loss, rejects CONNECT while offline, accepts only a strictly newer tunnel generation, ignores superseded callbacks, and never reuses a stream ID within one generation. Pending opens, admitted open rate, per-route application bytes, aggregate browser-host/process bytes, claims, and socket sources remain bounded with exact release on settlement and retirement. Queued transport drain yields after a bounded quantum. 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. Mint an exact execution-host grant, reject a different key, prove late old grant cleanup leaves its replacement, and invalidate every grant with lease replacement. 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. Across multiple routes, charge application copies, encrypted queue entries, and dynamic native socket bytes to one 32 MiB browser-host and 128 MiB process ceiling; reject zero-byte claim/socket-source floods, fence released leases, synchronously release JavaScript queue claims while retaining native claims through exact socket close, and yield a parked queue after four frames without reordering. Drop an authenticated transport, require the same listener to reject CONNECT before and during reconnect, attach the exact existing native v1 payload and capability pair to a strictly newer generation, ignore late old callbacks, and roll an exhausted stream-ID ledger only by replacing the generation. Require SSH descriptors to add the execution-host capability and exact grant, reject missing grants and stale provider authority before resolver or binary registration, pass exact domains to ssh2 and system-SSH SOCKS without local resolution, sanitize connector diagnostics, and close every stream and standalone route process once on timeout, synchronous failure, or rotation. Drive the accepted lease through real paired E2EE native SOCKS-to-HTTP and ephemeral Docker ssh2 remote-only DNS journeys, 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 or SSH provider authority, and server-owned route generation. A client page is usable only when its runtime ID, authority epoch, host identity and generation, logical page ID, page-host generation, current placement, and still-live lease all match atomically; a retired or server-placed page cannot be claimed as client placement. Live logical placements and their identities are bounded, while the runtime-wide page generation stays monotonic without tombstones. Non-native descriptors require explicit capability negotiation and an exact runtime-minted lease-bound execution-host grant. 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. A main-owned local listener remains stable across upstream transport loss, rejects CONNECT while offline, accepts only a strictly newer tunnel generation, ignores superseded callbacks, and never reuses a stream ID within one generation. Pending opens, admitted open rate, per-route application bytes, aggregate browser-host/process bytes, claims, and socket sources remain bounded with exact release on settlement and retirement. Queued transport drain yields after a bounded quantum. 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. Mint an exact execution-host grant, reject a different key, prove late old grant cleanup leaves its replacement, and invalidate every grant with lease replacement. 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. Require a client page through the exact runtime, epoch, host, and page tuple; reject every mismatch, released or replaced leases, retired pages, server placements, invalid identities, and the 257th live placement while allowing exact replacement at capacity. 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. Across multiple routes, charge application copies, encrypted queue entries, and dynamic native socket bytes to one 32 MiB browser-host and 128 MiB process ceiling; reject zero-byte claim/socket-source floods, fence released leases, synchronously release JavaScript queue claims while retaining native claims through exact socket close, and yield a parked queue after four frames without reordering. Drop an authenticated transport, require the same listener to reject CONNECT before and during reconnect, attach the exact existing native v1 payload and capability pair to a strictly newer generation, ignore late old callbacks, and roll an exhausted stream-ID ledger only by replacing the generation. Require SSH descriptors to add the execution-host capability and exact grant, reject missing grants and stale provider authority before resolver or binary registration, pass exact domains to ssh2 and system-SSH SOCKS without local resolution, sanitize connector diagnostics, and close every stream and standalone route process once on timeout, synchronous failure, or rotation. Drive the accepted lease through real paired E2EE native SOCKS-to-HTTP and ephemeral Docker ssh2 remote-only DNS journeys, 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/main/runtime/browser-host-page-placement.test.ts src/main/runtime/browser-host-lease-registry.test.ts",
         "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",
         "pnpm exec vitest run --config config/vitest.config.ts src/main/browser/browser-network-tunnel-outbound-memory-budget.test.ts src/main/browser/browser-network-tunnel-client-memory-budget.test.ts src/main/browser/browser-network-tunnel-session-aggregate-memory.test.ts src/shared/ws-outbound-backpressure-queue.test.ts src/shared/remote-runtime-client.test.ts",
@@ -2610,6 +2612,7 @@
         "src/shared/browser-network-capabilities.test.ts",
         "src/shared/browser-client-host-protocol.test.ts",
         "src/shared/browser-network-tunnel-protocol.test.ts",
+        "src/main/runtime/browser-host-page-placement.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",
@@ -2635,6 +2638,15 @@
         "tests/e2e/ssh-browser-network-execution-route.docker.unit.test.ts"
       ],
       "assertionRefs": [
+        {
+          "file": "src/main/runtime/browser-host-page-placement.test.ts",
+          "assertions": [
+            "client placement requires the exact runtime, epoch, host, and page generation on a live lease",
+            "lease release and replacement fence an otherwise matching client placement",
+            "retired, replaced, and server placements cannot be claimed as live client pages",
+            "live placement count and page/host identities are bounded before generation allocation"
+          ]
+        },
         {
           "file": "src/main/runtime/browser-host-lease-registry.test.ts",
           "assertions": [
@@ -2841,6 +2853,15 @@
         }
       ],
       "evidenceRuns": [
+        {
+          "date": "2026-08-14",
+          "runner": "local",
+          "platform": "macos",
+          "command": "pnpm exec vitest run --config config/vitest.config.ts src/main/runtime/browser-host-page-placement.test.ts src/main/runtime/browser-host-lease-registry.test.ts",
+          "result": "passed",
+          "durationSeconds": 0.2,
+          "summary": "Two files passed 17 exact runtime/epoch/host/page authority, live-lease fencing, monotonic replacement, invalid-identity, default 256-placement capacity, and stale-cleanup tests."
+        },
         {
           "date": "2026-08-14",
           "runner": "local",

src/main/runtime/browser-host-lease-registry.ts

@@ -1,5 +1,11 @@
 import { randomUUID } from 'node:crypto'
 import { BrowserExecutionHostGrantRegistry } from './browser-execution-host-grant-registry'
+import {
+  BrowserHostPagePlacementRegistry,
+  type BrowserClientPageAuthority,
+  type RuntimeBrowserClientPlacement,
+  type RuntimeBrowserPlacement
+} from './browser-host-page-placement'
 import {
   createBrowserHostFence,
   type BrowserHostFence,
@@ -11,14 +17,7 @@ const MAX_BROWSER_HOSTS_PER_CONNECTION = 1
 // Why: tolerate brief desktop restart/update overlap while keeping one paired identity bounded.
 const MAX_BROWSER_HOSTS_PER_PAIRED_DEVICE = 4
 
-export type RuntimeBrowserPlacement =
-  | { kind: 'server' }
-  | {
-      kind: 'client'
-      browserHostClientId: string
-      browserHostGeneration: number
-      pageHostGeneration: number
-    }
+export type { RuntimeBrowserPlacement } from './browser-host-page-placement'
 
 export type BrowserHostLease = Readonly<{
   authorityRuntimeId: string
@@ -68,16 +67,18 @@ export class BrowserHostLeaseRegistry {
   readonly authorityRuntimeId: string
   readonly authorityEpoch: string
   private nextHostGeneration = 1
-  // Why: a global counter lets closed page IDs leave no tombstone without reusing a stale generation.
-  private nextPageGeneration = 1
   private nextTunnelGeneration = 1
   private readonly leasesByClientId = new Map<string, LeaseState>()
   private readonly routesByKey = new Map<string, RouteState>()
-  private readonly placementsByPageId = new Map<string, RuntimeBrowserPlacement>()
+  private readonly pagePlacements: BrowserHostPagePlacementRegistry
 
   constructor(options: { authorityRuntimeId: string; authorityEpoch?: string }) {
     this.authorityRuntimeId = options.authorityRuntimeId
     this.authorityEpoch = options.authorityEpoch ?? randomUUID()
+    this.pagePlacements = new BrowserHostPagePlacementRegistry({
+      authorityRuntimeId: this.authorityRuntimeId,
+      authorityEpoch: this.authorityEpoch
+    })
   }
 
   attach(input: {
@@ -175,33 +176,35 @@ export class BrowserHostLeaseRegistry {
   }
 
   placeServerPage(browserPageId: string): RuntimeBrowserPlacement {
-    const placement = Object.freeze({ kind: 'server' as const })
-    this.placementsByPageId.set(browserPageId, placement)
-    return placement
+    return this.pagePlacements.placeServerPage(browserPageId)
   }
 
   placeClientPage(browserPageId: string, browserHostClientId?: string): RuntimeBrowserPlacement {
     const lease = this.select(browserHostClientId)
-    const pageHostGeneration = this.takePageGeneration()
-    const placement = Object.freeze({
-      kind: 'client' as const,
+    return this.pagePlacements.placeClientPage(browserPageId, {
       browserHostClientId: lease.browserHostClientId,
-      browserHostGeneration: lease.browserHostGeneration,
-      pageHostGeneration
+      browserHostGeneration: lease.browserHostGeneration
     })
-    this.placementsByPageId.set(browserPageId, placement)
+  }
+
+  requireClientPage(authority: BrowserClientPageAuthority): RuntimeBrowserClientPlacement {
+    const placement = this.pagePlacements.requireClientPage(authority)
+    const lease = this.leasesByClientId.get(authority.browserHostClientId)
+    if (!lease) {
+      throw new Error('browser_host_lease_required')
+    }
+    if (lease.lease.browserHostGeneration !== authority.browserHostGeneration) {
+      throw new Error('browser_host_lease_stale')
+    }
     return placement
   }
 
   getPlacement(browserPageId: string): RuntimeBrowserPlacement | undefined {
-    return this.placementsByPageId.get(browserPageId)
+    return this.pagePlacements.getPlacement(browserPageId)
   }
 
   retirePage(browserPageId: string, expected: RuntimeBrowserPlacement): boolean {
-    if (this.placementsByPageId.get(browserPageId) !== expected) {
-      return false
-    }
-    return this.placementsByPageId.delete(browserPageId)
+    return this.pagePlacements.retirePage(browserPageId, expected)
   }
 
   openTunnel(
@@ -300,15 +303,6 @@ export class BrowserHostLeaseRegistry {
     }
     return value
   }
-
-  private takePageGeneration(): number {
-    const value = this.nextPageGeneration
-    if (value > MAX_GENERATION) {
-      throw new Error('browser_page_generation_exhausted')
-    }
-    this.nextPageGeneration += 1
-    return value
-  }
 }
 
 const registries = new WeakMap<object, BrowserHostLeaseRegistry>()