Add isolated transport broker

docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-> Status: draft | Updated 2026-07-07 | Applies to: AMPB contributors and integrators
+> Status: draft | Updated 2026-07-11 | Applies to: AMPB contributors and integrators
 
 AMPB is a browser orchestration layer for privacy, resilient-network, content-addressed,
 and alternate-web transports. It keeps the routing, transport management, and profile
@@ -16,12 +16,20 @@ isolation decisions outside the browser engine until those contracts are stable.
 6. Start or install managed transports only after user consent.
 7. Open the URL with the matching isolated profile.
 
+The clearnet entry profile is a broker, not a mixed-network profile. It uses direct
+clearnet networking. Its extension blocks all `.onion` and `.i2p` requests from that
+profile. For a top-level navigation, it asks a token-gated loopback helper to apply the
+normal route and consent policy, then opens the destination in a separate transport
+profile and browser process.
+
 ## Main Components
 
 - `ampbrowser.routing`: deterministic URL-to-transport rules.
 - `ampbrowser.adapters`: transport ownership, setup, inspection, and health contracts.
 - `ampbrowser.transports`: local readiness checks for Tor, I2P, IPFS, Reticulum, and Gemini.
 - `ampbrowser.plan`: dry-run action planner for browser launches.
+- `ampbrowser.broker`: validated handoff from the clearnet entry profile to an isolated
+  transport profile.
 - `ampbrowser.launch`: side-effect-free launch specs and first-use consent state.
 - `ampbrowser.platforms`: platform capability matrix for desktop, Android, and iOS.
 - `ampbrowser.candidates`: evaluated transport candidates before active adapter support.
@@ -49,8 +57,21 @@ Generated backend metadata lives in
 
 The first implementation path is documented in [desktop vertical](desktop-vertical.md).
 
+## Isolation Boundaries
+
+- Browser storage is isolated by transport profile.
+- Transport runtime state is isolated under AMPB-owned transport directories when AMPB
+  manages the daemon.
+- A transport profile remains sticky: ordinary navigation stays in that profile and uses
+  its configured proxy until the user explicitly starts a different context.
+- The loopback helper accepts a random per-launch token and recomputes the URL route before
+  opening it. A caller cannot label an I2P URL as Tor or vice versa.
+
+These controls prevent accidental browser-state mixing. They do not by themselves provide
+Tor Browser fingerprinting resistance or make non-anonymous transports anonymous.
+
 ## Relationship To AMPG
 
-AMPG publishes protocol-specific site variants. AMPB opens those variants with the right
-transport and profile. Wownero is the shared fixture for static publishing, while
-interactive targets exercise sessions, dynamic assets, forms, and script policy.
+AMPG publishes protocol-specific site variants and declares their expected transport,
+profile, and isolation mode in fixture manifests. AMPB validates and enforces the browser
+side of that contract. AMPG never controls local browser daemon ownership or profile state.

docs/broker.md

@@ -0,0 +1,44 @@
+# Transport Broker
+
+> Status: draft | Updated 2026-07-11 | Applies to: AMPB desktop users and implementers
+
+The transport broker is AMPB's clearnet entry profile. It gives users one place to begin
+without combining clearnet, Tor, and I2P browser storage or proxy policy.
+
+## Handoff
+
+1. The broker profile begins a top-level navigation.
+2. Its extension recognizes `.onion` or `.i2p` and cancels the request.
+3. A token-gated loopback helper independently routes the URL.
+4. If needed, AMPB asks for first-use consent and starts or adopts the transport.
+5. AMPB opens the URL in `.ampb/profiles/tor` or `.ampb/profiles/i2p` with that profile's
+   proxy policy.
+6. The broker tab reports that the route opened in an isolated context.
+
+AMPB records the process it launches for each exact profile. Later handoffs reuse only a
+live process recorded for that profile; otherwise AMPB launches a new isolated process.
+
+The helper rejects a handoff when the supplied transport does not match the URL. It is
+tied to the broker browser process and stops when that process exits.
+
+Subresources, frames, and background requests to alternate-network hosts are blocked in
+the clearnet broker and are not converted into handoffs. Only top-level navigation can
+open another transport context.
+
+## Boundaries
+
+The broker separates cookies, cache, history, service workers, and other profile storage
+by transport. AMPB-managed daemon state is separately stored under
+`.ampb/transports/<transport>`.
+
+Transport isolation is not an anonymity claim. Tor browsing still requires Tor Browser
+hardening and update parity before AMPB can claim equivalent fingerprinting resistance.
+I2P and Reticulum have different threat models and must be described on their own terms.
+
+## Command
+
+```sh
+python3 -m ampbrowser open https://ampgateway.site/ --broker --launch
+```
+
+`--route-aware` is retained as a compatibility alias for `--broker`.

docs/desktop-vertical.md

@@ -27,9 +27,10 @@ artifacts are available for the selected checkout.
 ## Transport Path
 
 The first transport target is Tor through an AMPB-owned Arti/Tor runtime. The current
-desktop vertical can launch a bundled Gecko runtime, start a route-aware helper, and keep
-the helper tied to the browser process. I2P uses the same route, consent, state, and
-health-check model. Reticulum follows after the resilient-network adapter is concrete.
+desktop vertical can launch a bundled Gecko runtime, start the isolated transport broker,
+and keep its token-gated helper tied to the broker process. Tor and I2P destinations launch
+in their own browser profiles after route validation and consent. Reticulum follows after
+the resilient-network adapter and renderer handoff are concrete.
 
 ## Desktop Shell
 
@@ -41,4 +42,5 @@ approval. Use `--yes` for scripted verification without showing the dialog.
 ```sh
 python3 -m ampbrowser shell http://example.onion/
 python3 -m ampbrowser shell http://example.onion/ --yes
+python3 -m ampbrowser shell https://ampgateway.site/ --broker
 ```

docs/fixture-manifests.md

@@ -1,10 +1,11 @@
 # Fixture Manifests
 
-> Status: draft | Updated 2026-07-06 | Applies to: AMPB and AMPG compatibility checks
+> Status: draft | Updated 2026-07-11 | Applies to: AMPB and AMPG compatibility checks
 
 AMPB can check AMPG fixture manifests without contacting any network. The check confirms
-that each generated fixture URL routes to the expected AMPB transport and profile, and
-that its declared interaction policy fits that transport.
+that each generated fixture URL routes to the expected AMPB transport and profile, uses
+the declared transport-profile isolation contract, and fits that transport's interaction
+policy.
 
 Route-expanded fixtures may include `route.match` and `route.fixture_path`, which identify
 the route group that produced the fixture.
@@ -20,8 +21,9 @@ manifest.
 
 ## Scope
 
-Fixture checks validate route selection and declared interaction policy only. They do not
-verify daemon health, hidden service reachability, IPFS pinning, TLS, or content freshness.
+Fixture checks validate route selection, profile isolation expectations, and declared
+interaction policy only. They do not verify process separation, daemon health, hidden
+service reachability, IPFS pinning, TLS, or content freshness.
 
 The manifest must not contain private deployment notes, service keys, credentials, or
 host inventory.

docs/open-flow.md

@@ -34,13 +34,12 @@ adopted daemon from an AMPB-owned managed process.
 through a desktop dialog when possible, falls back to a terminal prompt when needed, and
 launches through the same transport runner after approval.
 
-`ampbrowser open <url> --route-aware --launch` creates a desktop convenience profile for
-clearnet, Tor, and I2P QA. The profile uses a PAC file for `.onion` and `.i2p` routing,
-installs the AMPB route-helper extension, and starts a token-gated loopback helper tied
-to the browser process. If a user clicks an alternate-network link before its local
-transport is ready, the extension shows a setup page and asks the helper to start the
-AMPB-managed transport after approval. This mode proves routing and first-use setup; it
-is not the final per-transport storage isolation model.
+`ampbrowser open <clearnet-url> --broker --launch` creates the desktop entry profile. The
+broker has direct clearnet networking and no mixed-transport PAC. Its extension cancels
+all `.onion` and `.i2p` requests before they leave the profile. For a top-level navigation,
+it asks a token-gated loopback helper to open the URL in the isolated Tor or I2P profile.
+Missing transports use the same first-use consent flow before the handoff. `--route-aware`
+remains a compatibility alias for `--broker`.
 
 ## Examples
 
@@ -51,7 +50,7 @@ python3 -m ampbrowser open http://example.b32.i2p/ --yes
 python3 -m ampbrowser open http://example.b32.i2p/ --config examples/config.toml
 python3 -m ampbrowser open http://example.b32.i2p/ --platform android
 python3 -m ampbrowser open https://wownero.org/ --launch
-python3 -m ampbrowser open https://ampgateway.site/ --route-aware --launch
+python3 -m ampbrowser open https://ampgateway.site/ --broker --launch
 python3 -m ampbrowser open http://example.onion/ --launch
 python3 -m ampbrowser open http://example.onion/ --yes --launch
 python3 -m ampbrowser shell http://example.onion/