@reclaimprotocol/agent 0.1.29 → 0.1.31

package/README.md

@@ -6,6 +6,18 @@ Under the hood it's Chrome-CDP + zkTLS provider-authoring tooling: it captures n
 
 This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depends on `@reclaimprotocol/client` for the typed HTTP client and registers the provider-authoring tools below alongside the backend-facing tools (credentials, publishing) in a single MCP surface. A standalone entry (`src/index.ts`) re-exports the client SDK plus `buildAgentTools` for embedding.
 
+## Contents
+
+- [Install](#install)
+- [Use it from an agent](#using-it-from-your-agent)
+- [Provider-authoring tools](#provider-authoring-tools)
+- [Backends](#backends)
+- [Local development](#local-development-from-source)
+- [Platform notes](#platform-notes)
+- [Tests](#tests)
+- [Disable browser tools](#disable-the-browser-tools)
+- [Contributor setup](#for-contributors--wiring-a-local-build-into-claude-code--opencode)
+
 ## Install
 
 **Prerequisites:**
@@ -13,7 +25,7 @@ This package **is** the Reclaim MCP server (bin: `reclaim-mcp-server`). It depen
 - **Node 20 or later.** Any line works, including non-LTS ones such as 25, but a current LTS line (22 or 24) is recommended.
 - **A local Chrome, Chromium, or Edge**, used for capture and for the dashboard login.
 - **Docker** — only for `attach_browser`'s `container` mode, which runs the Reclaim browser runtime (the same image the hosted browser uses) and gives you a link you can send to whoever holds the account. It is the free way to get that link; the hosted remote browser is the other, and it is chargeable. Not needed if you are doing the work yourself. The image is amd64, so Apple Silicon runs it translated. OrbStack handles that itself; Docker Desktop needs Rosetta enabled. `RECLAIM_BROWSER_RUNTIME_IMAGE` overrides the pinned digest.
-- **`cloudflared`** — not required up front. `share_browser_view` uses an existing install if one is on `PATH`, and otherwise downloads it once to `~/.reclaim/bin` on first share (never at install time). Set `RECLAIM_CLOUDFLARED_PATH` to point at your own copy.
+- **`cloudflared`** — only to share a `container` browser with someone remote. The MCP server does not run or install it: `share_browser_view` returns the command, and the agent runs `cloudflared tunnel --url http://localhost:<port>` itself, so install it yourself first.
 
 The first time you call `run_proof`, the agent downloads the ZK circuit files it needs (about 280 MB), so allow a moment for that first proof. The download is deferred to the first proof rather than run at install time, so the MCP server itself starts immediately.
 
@@ -27,7 +39,7 @@ npx -y --package=@reclaimprotocol/agent reclaim-mcp-server
 
 ### Installing into your coding agent
 
-Copy-paste setup for **Claude Code** (plugin marketplace), **Claude Desktop**, **Cursor**, **opencode**, **Codex**, **Windsurf**, **VS Code**, **Cline** and other MCP clients lives in the public **[reclaimprotocol/developer-tools](https://github.com/reclaimprotocol/developer-tools)** repo — that's where the Claude Code plugin/marketplace is published.
+Copy-paste setup for **Claude Code** (plugin marketplace), **Codex** (plugin marketplace), **Claude Desktop**, **Cursor**, **opencode**, **Windsurf**, **VS Code**, **Cline** and other MCP clients lives in the public **[reclaimprotocol/developer-tools](https://github.com/reclaimprotocol/developer-tools)** repo — that's where the Claude Code and Codex plugins are published.
 
 The quickest path, in Claude Code:
 
@@ -36,11 +48,18 @@ The quickest path, in Claude Code:
 /plugin install reclaim@reclaim
 ```
 
+In Codex:
+
+```bash
+codex plugin marketplace add reclaimprotocol/developer-tools
+codex plugin add reclaim@reclaim
+```
+
 For any other client, point it at the stdio command above (`npx -y --package=@reclaimprotocol/agent reclaim-mcp-server`) — see the developer-tools README for per-client config and the Claude Desktop / GUI-app notes.
 
 ### Optional environment
 
-Defaults target the production old-devtools backend, so **no env is needed for the common case**. To override, add an `env` block (or `environment` in opencode) to the config above:
+Defaults target the Builder backend, so **no env is needed for the common case**. To use legacy devtools explicitly, add an `env` block (or `environment` in opencode):
 
 ```json
 "env": {
@@ -49,7 +68,7 @@ Defaults target the production old-devtools backend, so **no env is needed for t
 }
 ```
 
-See [Backends](#backends) for builder mode (`USE_OLD_DEVTOOLS=false`) and the full env-var list.
+See [Backends](#backends) for the full env-var list.
 
 ### Provider-authoring guide
 
@@ -101,21 +120,21 @@ These capture/synthesis/proof tools are backend-independent and registered in bo
 | `create_provider_version_from_capture`      | Publish a draft as a new immutable semantic version (patch by default)                                         |
 | `authenticate_builder`                      | In old-devtools mode only, sign in to Builder for remote-browser allocation                                   |
 | `list_builder_organizations`                | In old-devtools mode only, list organization ids for a quota-accounted Builder browser                         |
-| `share_browser_view`, `stop_browser_view`   | Put the `container` browser's own live view behind a public HTTPS URL (cloudflared quick tunnel), so someone elsewhere can watch it and act in it — from a phone if they like. Container mode only: a `builder` browser already returns a hosted `liveViewUrl`, and a plain local browser has no view to share |
+| `share_browser_view`                        | Share the `container` browser's own live view with someone elsewhere. Returns the local viewer port and the `cloudflared tunnel` command for the agent to run; call it again with the printed `https://*.trycloudflare.com` URL as `publicUrl` to get the link to relay. Container mode only: a `builder` browser already returns a hosted `liveViewUrl`, and a plain local browser has no view to share |
 | `dispose_browser`                           | Stop captures, disconnect CDP, and immediately release a Builder-hosted browser                               |
 | `get_session`, `reset_session`              | Session state                                                                                                  |
 
 ## Backends
 
-The MCP server targets one of two backends, selected by `USE_OLD_DEVTOOLS`:
+The MCP server targets one of two backends. An explicit `USE_OLD_DEVTOOLS` setting overrides the persisted choice; otherwise Builder is the default:
 
-- **Old devtools (default).** The legacy devtools backend is still in production while the new "builder" backend is built, so this is the default — opt into builder with `USE_OLD_DEVTOOLS=false`. In old mode all auto-generated HTTP-API tools are disabled and a small client (`src/old/`) serves:
+- **Old devtools (`USE_OLD_DEVTOOLS=true`).** In old mode all auto-generated HTTP-API tools are disabled and a small client (`src/old/`) serves:
   - `reclaim_authenticate` — by default opens the dashboard in local Chrome over loopback CDP, waits for sign-in, reads the Firebase token from page storage, and closes the tab. It never uses a remote or shared authoring browser. Pass a `token` / `ethAddress` to skip the browser.
   - `create_provider_version_from_capture` — registers a new provider, or adds a new immutable semantic version when given a `providerId`. It never edits an existing version.
   - `get_me_providers` — list the providers you own (the only provider-listing tool in this mode).
   - `session_analytics_logs` — the milestone events for a verification session, which show how far it got.
   - `session_logs` — the log entries the in-app SDK emitted during that session, each with its event type, log level, and logger name. Filter by event type, level, or substring, page with `limit` and `offset`, or set `saveTo` to write every matching entry to an NDJSON file. The backend searches only the last 3 days unless you pass `startTime` and `endTime`, and it deletes entries after 30 days.
-- **Builder (`USE_OLD_DEVTOOLS=false`).** Registers the auto-generated HTTP-API tools plus the authentication/credential tools (`authenticate` device-pairing login, `issue_credentials` / `import_credentials` to set up the local eth proof-owner key, `resolve_owner_key`) and a verification-result helper (`get_verification_result`).
+- **Builder (default).** Registers the auto-generated HTTP-API tools, including `create_org`, `issue_org_token`, and `create_org_callback_subscription`, plus authentication/credential tools and `get_verification_result`. `issue_credentials` creates a local proof-owner key; `issue_org_token` issues the organization's API secret.
 
 Relevant env vars: `RECLAIM_OLD_API_URL` (default `https://devapi.reclaimprotocol.org`), `RECLAIM_OLD_API_TOKEN` / `RECLAIM_OLD_ETH_UID` (headless identity), `RECLAIM_OLD_LOGIN_URL` (default `https://dev.reclaimprotocol.org`); builder mode uses `RECLAIM_API_URL` / `RECLAIM_API_TOKEN`.
 
@@ -214,7 +233,7 @@ claude mcp add reclaim -- node "$(pwd)/packages/agent/lib/mcp-bin.js"
 }
 ```
 
-To target a specific backend while developing, add an `env` block (Claude Code / `.mcp.json`) or `environment` (opencode) — for example, `"USE_OLD_DEVTOOLS": "false"` for builder mode. See [Backends](#backends).
+To override the default backend while developing, add an `env` block (Claude Code / `.mcp.json`) or `environment` (opencode) with `"USE_OLD_DEVTOOLS": "true"` for legacy devtools. See [Backends](#backends).
 
 ### Authoring guide
 

package/lib/consts.d.ts

@@ -31,14 +31,14 @@ export declare const LOG_LEVEL: string;
 export declare function reclaimHome(): string;
 /**
  * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
- * server targets. Defaults to OLD devtools while the builder backend is under
- * development. Builder mode must be opted into EXPLICITLY with
- * `USE_OLD_DEVTOOLS=false`; anything else keeps old mode on.
+ * server targets. Builder is the default. Set `USE_OLD_DEVTOOLS=true` to
+ * explicitly use the legacy backend.
  */
 export declare function useOldDevtools(): boolean;
 /**
  * Effective mode, layering the persisted preference under the env var:
- * explicit `USE_OLD_DEVTOOLS` wins → persisted config `mode` → default (old).
+ * explicit `USE_OLD_DEVTOOLS` wins → persisted config `mode` →
+ * default (builder).
  * The persisted value comes from `~/.reclaim/config.json` (set via the
  * `set_devtools_mode` tool); the caller reads it so this module needn't import
  * `ConfigStore` (which would create an import cycle).
@@ -47,7 +47,7 @@ export declare function resolveOldMode(persisted?: 'old' | 'builder'): boolean;
 /**
  * Where the effective mode came from — the same precedence as
  * `resolveOldMode`: explicit `USE_OLD_DEVTOOLS` env var → persisted config
- * `mode` → default (old). Surfaced by the `get_devtools_mode` tool so the
+ * `mode` → default (builder). Surfaced by the `get_devtools_mode` tool so the
  * user can tell why the server is in the mode it reports.
  */
 export declare function oldModeSource(persisted?: 'old' | 'builder'): 'env' | 'config' | 'default';

package/lib/consts.js

@@ -49,12 +49,11 @@ export function reclaimHome() {
 // ---------------------------------------------------------------------------
 /**
  * `USE_OLD_DEVTOOLS` — single source of truth for which backend the MCP
- * server targets. Defaults to OLD devtools while the builder backend is under
- * development. Builder mode must be opted into EXPLICITLY with
- * `USE_OLD_DEVTOOLS=false`; anything else keeps old mode on.
+ * server targets. Builder is the default. Set `USE_OLD_DEVTOOLS=true` to
+ * explicitly use the legacy backend.
  */
 export function useOldDevtools() {
-    return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false';
+    return ['true', '1'].includes((process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase());
 }
 /** True when `USE_OLD_DEVTOOLS` is set to a non-empty value (explicit). */
 function oldDevtoolsEnvSet() {
@@ -62,7 +61,8 @@ function oldDevtoolsEnvSet() {
 }
 /**
  * Effective mode, layering the persisted preference under the env var:
- * explicit `USE_OLD_DEVTOOLS` wins → persisted config `mode` → default (old).
+ * explicit `USE_OLD_DEVTOOLS` wins → persisted config `mode` →
+ * default (builder).
  * The persisted value comes from `~/.reclaim/config.json` (set via the
  * `set_devtools_mode` tool); the caller reads it so this module needn't import
  * `ConfigStore` (which would create an import cycle).
@@ -74,12 +74,12 @@ export function resolveOldMode(persisted) {
     if (persisted) {
         return persisted === 'old';
     }
-    return true;
+    return false;
 }
 /**
  * Where the effective mode came from — the same precedence as
  * `resolveOldMode`: explicit `USE_OLD_DEVTOOLS` env var → persisted config
- * `mode` → default (old). Surfaced by the `get_devtools_mode` tool so the
+ * `mode` → default (builder). Surfaced by the `get_devtools_mode` tool so the
  * user can tell why the server is in the mode it reports.
  */
 export function oldModeSource(persisted) {

package/lib/live/tunnel-watchdog.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/live/tunnel-watchdog.js

@@ -0,0 +1,66 @@
+/**
+ * Own cloudflared on behalf of one MCP process.
+ *
+ * A normal child survives when its Node parent crashes: the OS reparents it and
+ * the old public hostname keeps pointing at a viewer port that no longer
+ * exists.
+ * This small process stays between MCP and cloudflared, checks the original
+ * owner's PID, and tears cloudflared down when that owner disappears.
+ */
+import { spawn } from 'node:child_process';
+const [ownerValue, binary, ...args] = process.argv.slice(2);
+const ownerPid = Number(ownerValue);
+if (!Number.isInteger(ownerPid) || ownerPid <= 0 || !binary) {
+    process.stderr.write('Invalid tunnel-watchdog arguments.\n');
+    process.exit(2);
+}
+const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+let stopping = false;
+let forceTimer;
+// A dead MCP closes these pipes. Ignore EPIPE while the watchdog finishes the
+// more important job of terminating cloudflared.
+process.stdout.on('error', () => { });
+process.stderr.on('error', () => { });
+child.stdout.on('data', (chunk) => process.stdout.write(chunk));
+child.stderr.on('data', (chunk) => process.stderr.write(chunk));
+const ownerTimer = setInterval(() => {
+    if (!processAlive(ownerPid)) {
+        stop();
+    }
+}, 1000);
+child.on('error', (error) => {
+    process.stderr.write(`Could not start cloudflared: ${error.message}\n`);
+});
+child.on('exit', (code, signal) => {
+    clearInterval(ownerTimer);
+    clearTimeout(forceTimer);
+    process.exitCode = stopping ? 0 : code ?? (signal ? 1 : 0);
+});
+process.once('SIGINT', stop);
+process.once('SIGTERM', stop);
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code === 'EPERM';
+    }
+}
+function stop() {
+    if (stopping) {
+        return;
+    }
+    stopping = true;
+    clearInterval(ownerTimer);
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    child.kill('SIGTERM');
+    forceTimer = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGKILL');
+        }
+    }, 5000);
+    forceTimer.unref();
+}

package/lib/live/tunnel.d.ts

@@ -12,13 +12,20 @@ export interface Tunnel {
     binary: CloudflaredBinary;
 }
 /**
- * Open a quick tunnel to `http://127.0.0.1:<port>` and resolve once
- * Cloudflare has assigned a hostname.
- *
- * Rejects with an actionable message when `cloudflared` is not installed,
- * exits early, or never reports a hostname.
+ * The probe's verdict, plus — on failure — which component said no. Carrying
+ * the reason forward means the error a caller eventually sees names the
+ * actual failing part (a specific DNS resolver, the viewer document, or a
+ * specific WebSocket path) instead of a bare "not ready" that leaves the next
+ * person to guess.
  */
-export declare function startTunnel(port: number, { autoInstall, probePath, readyPollMs, readyTimeoutMs, }?: {
+type ProbeResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+type RouteProbe = (url: string, timeoutMs: number) => Promise<ProbeResult>;
+export interface StartTunnelOptions {
     autoInstall?: boolean;
     /** Public path that must answer before the tunnel is returned. */
     probePath?: string;
@@ -26,4 +33,20 @@ export declare function startTunnel(port: number, { autoInstall, probePath, read
     readyPollMs?: number;
     /** Test-only timing override. */
     readyTimeoutMs?: number;
-}): Promise<Tunnel>;
+    /** Test-only delay after cloudflared confirms route registration. */
+    registeredSettleMs?: number;
+    /** Test-only public-route probe override. */
+    probe?: RouteProbe;
+}
+/**
+ * Open a quick tunnel to `http://127.0.0.1:<port>` and resolve once
+ * Cloudflare has assigned a hostname AND it has been proven publicly routed.
+ *
+ * Rejects with an actionable message when `cloudflared` is not installed,
+ * exits early, or never reports a hostname. When a hostname is assigned but
+ * fails its readiness probe, this retries with a fresh hostname up to
+ * MAX_TUNNEL_ATTEMPTS times before giving up — see that constant for why the
+ * SAME hostname is never retried.
+ */
+export declare function startTunnel(port: number, options?: StartTunnelOptions): Promise<Tunnel>;
+export {};

package/lib/live/tunnel.js

@@ -19,19 +19,45 @@
  * is unauthenticated total control of the browser.
  */
 import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import { LOGGER } from "../logger.js";
 import { resolveCloudflared } from "./cloudflared.js";
 /** How long to wait for cloudflared to report its hostname before giving up. */
 const URL_TIMEOUT_MS = 30000;
-/** After the hostname is printed, Cloudflare needs time before the edge routes
- *  to it. Probe briefly, then return the still-running tunnel as propagating so
- *  slow DNS or edge setup does not destroy an otherwise healthy share. */
-const READY_TIMEOUT_MS = 20000;
+/** Never hand out a hostname before public DNS and the edge both carry the
+ * viewer. Opening an unready hostname can leave a remote browser with a cached
+ * NXDOMAIN response after the route itself becomes healthy. */
+const READY_TIMEOUT_MS = 60000;
 const READY_POLL_MS = 1000;
+const PROBE_TIMEOUT_MS = 10000;
+/** Avoid asking recursive DNS for the hostname during the short interval
+ * between quick-tunnel allocation and route registration. An early NXDOMAIN
+ * can be cached for 30 minutes, making the link work for some users only. */
+const REGISTERED_SETTLE_MS = 2000;
+/**
+ * Total hostnames to try before giving up: the first, plus one fresh one. A
+ * hostname that fails the readiness probe does not recover on its own — see
+ * REGISTERED_SETTLE_MS above — so retrying the SAME hostname spends the whole
+ * timeout on a route that cannot come back. A new `cloudflared` invocation
+ * mints a new random hostname, unaffected by whatever public resolver cached
+ * the old one's NXDOMAIN, so a fresh hostname is where the recovery odds
+ * actually are. A third hostname would cost the caller another full
+ * READY_TIMEOUT_MS without materially better odds, so this stays at two: the
+ * same bound the live-view skill already tells a caller to apply by hand
+ * ("retry once to request a fresh one").
+ */
+const MAX_TUNNEL_ATTEMPTS = 2;
 const STOP_TIMEOUT_MS = 5000;
+const WATCHDOG_PATH = fileURLToPath(new URL('./tunnel-watchdog.js', import.meta.url));
 /** `https://<something>.trycloudflare.com`, as printed on cloudflared's log
  *  stream. Anchored to the scheme so a hostname inside prose can't match. */
 const QUICK_TUNNEL_URL = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+const REGISTERED_TUNNEL = 'Registered tunnel connection';
+const PUBLIC_DNS_RESOLVERS = [
+    'https://cloudflare-dns.com/dns-query',
+    'https://dns.google/resolve',
+];
+const VIEWER_WEBSOCKET_PATHS = ['/websockify?keep=1', '/input', '/kbd'];
 /** Tail of cloudflared's log kept for error messages. */
 const LOG_TAIL_BYTES = 4096;
 /**
@@ -41,42 +67,189 @@ const LOG_TAIL_BYTES = 4096;
  * can report one while the assigned hostname still returns DNS NXDOMAIN. The
  * public viewer itself must return a successful response.
  */
-async function waitUntilRouted(url, { isRunning, pollMs, timeoutMs, }) {
+async function waitUntilRouted(url, { isRunning, pollMs, probe, timeoutMs, }) {
     const deadline = Date.now() + timeoutMs;
+    let lastReason;
     while (Date.now() < deadline) {
         if (!isRunning()) {
-            return false;
+            return { ready: false, reason: lastReason };
         }
-        try {
-            const response = await fetch(url, {
-                method: 'GET',
-                redirect: 'manual',
-                signal: AbortSignal.timeout(pollMs * 2),
-            });
-            if (response.ok) {
-                return true;
-            }
+        const remainingMs = deadline - Date.now();
+        const result = await probe(url, Math.min(PROBE_TIMEOUT_MS, remainingMs));
+        if (result.ok) {
+            return { ready: true };
         }
-        catch { }
+        lastReason = result.reason;
         await new Promise((r) => setTimeout(r, pollMs));
     }
-    return false;
+    return { ready: false, reason: lastReason };
+}
+/**
+ * Require independent public DNS resolvers, the viewer document, and every
+ * viewer WebSocket to work. This represents the path another user takes; a
+ * healthy Docker browser or loopback viewer alone is insufficient.
+ *
+ * The three stages share ONE deadline instead of each getting a fresh
+ * `timeoutMs`. Chaining them with independent budgets let one slow-to-fail
+ * stage (say, a DNS query that hangs for the full timeout) leave the later
+ * stages no time at all while still reporting as if the whole probe had spent
+ * only `timeoutMs` — in practice, up to three times that per call, which
+ * starves `waitUntilRouted` of the retries it needs while a cold tunnel warms
+ * up. A shared deadline keeps the caller's per-attempt budget honest.
+ *
+ * DNS is checked against every resolver, not a majority: the question this
+ * answers is "would an arbitrary remote viewer's own resolver see this host",
+ * and a viewer's resolver could be either one. Weakening this to a majority
+ * would let a link through that fails for whoever happens to use the
+ * lagging resolver — the exact false positive this probe exists to prevent.
+ */
+async function probePublicRoute(url, timeoutMs) {
+    const parsed = new URL(url);
+    const deadline = Date.now() + timeoutMs;
+    const remainingMs = () => Math.max(1, deadline - Date.now());
+    try {
+        const dnsResults = await Promise.all(PUBLIC_DNS_RESOLVERS.map((resolver) => resolvesThrough(resolver, parsed.hostname, remainingMs())));
+        const unresolved = PUBLIC_DNS_RESOLVERS[dnsResults.indexOf(false)];
+        if (unresolved) {
+            return {
+                ok: false,
+                reason: `public DNS resolver ${unresolved} does not resolve `
+                    + `${parsed.hostname} yet`,
+            };
+        }
+        const response = await fetch(parsed, {
+            signal: AbortSignal.timeout(remainingMs()),
+        });
+        if (response.status < 200 || response.status >= 400) {
+            return {
+                ok: false,
+                reason: `viewer document returned HTTP ${response.status}`,
+            };
+        }
+        await response.body?.cancel();
+        const websocketPaths = await Promise.all(VIEWER_WEBSOCKET_PATHS.map((path) => probeWebSocket(new URL(path, parsed).toString().replace(/^http/, 'ws'), remainingMs())));
+        const unconnected = VIEWER_WEBSOCKET_PATHS[websocketPaths.indexOf(false)];
+        if (unconnected) {
+            return {
+                ok: false,
+                reason: `viewer WebSocket ${unconnected} did not connect`,
+            };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function resolvesThrough(resolver, hostname, timeoutMs) {
+    const url = new URL(resolver);
+    url.searchParams.set('name', hostname);
+    url.searchParams.set('type', 'A');
+    const response = await fetch(url, {
+        headers: { accept: 'application/dns-json' },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) {
+        return false;
+    }
+    const payload = await response.json();
+    return typeof payload === 'object'
+        && payload !== null
+        && 'Status' in payload
+        && payload.Status === 0
+        && 'Answer' in payload
+        && Array.isArray(payload.Answer)
+        && payload.Answer.length > 0;
+}
+function probeWebSocket(url, timeoutMs) {
+    return new Promise((resolve) => {
+        const websocket = new WebSocket(url);
+        let settled = false;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            websocket.close();
+            resolve(result);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        websocket.addEventListener('open', () => finish(true), { once: true });
+        websocket.addEventListener('error', () => finish(false), { once: true });
+    });
+}
+/**
+ * A hostname's readiness probe never came back positive while cloudflared
+ * kept running. This is the one failure `startTunnel` retries with a fresh
+ * hostname: everything else (cloudflared missing, cloudflared exiting, no
+ * hostname ever reported) points at a problem a new hostname would not fix.
+ */
+class HostnameNotRoutedError extends Error {
+    constructor(message, cloudflaredLog) {
+        super(message);
+        this.name = 'HostnameNotRoutedError';
+        this.cloudflaredLog = cloudflaredLog;
+    }
 }
 /**
  * Open a quick tunnel to `http://127.0.0.1:<port>` and resolve once
- * Cloudflare has assigned a hostname.
+ * Cloudflare has assigned a hostname AND it has been proven publicly routed.
  *
  * Rejects with an actionable message when `cloudflared` is not installed,
- * exits early, or never reports a hostname.
+ * exits early, or never reports a hostname. When a hostname is assigned but
+ * fails its readiness probe, this retries with a fresh hostname up to
+ * MAX_TUNNEL_ATTEMPTS times before giving up — see that constant for why the
+ * SAME hostname is never retried.
  */
-export async function startTunnel(port, { autoInstall = true, probePath = '/', readyPollMs = READY_POLL_MS, readyTimeoutMs = READY_TIMEOUT_MS, } = {}) {
+export async function startTunnel(port, options = {}) {
     // Resolves an existing cloudflared, or fetches one on first use. Throws
-    // with an actionable message when neither is possible.
-    const binary = await resolveCloudflared({ autoInstall });
-    const child = spawn(binary.path, [
+    // with an actionable message when neither is possible. Resolved once, not
+    // per attempt: the binary is the same across retries, only the hostname
+    // changes.
+    const binary = await resolveCloudflared({ autoInstall: options.autoInstall });
+    for (let attempt = 1; attempt <= MAX_TUNNEL_ATTEMPTS; attempt++) {
+        try {
+            return await openTunnelAttempt(port, binary, options);
+        }
+        catch (err) {
+            if (!(err instanceof HostnameNotRoutedError)) {
+                throw err;
+            }
+            if (attempt < MAX_TUNNEL_ATTEMPTS) {
+                LOGGER.warn({ attempt, reason: err.message }, 'live view: hostname failed to route, trying a fresh one');
+                continue;
+            }
+            const retries = MAX_TUNNEL_ATTEMPTS - 1;
+            const retryWord = retries === 1 ? 'retry' : 'retries';
+            throw new Error(`${err.message} ${retries} automatic ${retryWord} with a fresh `
+                + 'hostname also failed to route. Call share_browser_view again '
+                + 'in a few minutes, or check network egress to Cloudflare.'
+                + '\ncloudflared output:\n' + err.cloudflaredLog);
+        }
+    }
+    // Unreachable: the loop above always returns from a successful attempt or
+    // throws once attempts are exhausted. Kept so a future change to the loop
+    // bounds can't silently fall through without returning a Tunnel.
+    throw new Error('startTunnel: exhausted attempts without a result');
+}
+async function openTunnelAttempt(port, binary, { probePath = '/', readyPollMs = READY_POLL_MS, readyTimeoutMs = READY_TIMEOUT_MS, registeredSettleMs = REGISTERED_SETTLE_MS, probe = probePublicRoute, }) {
+    const cloudflaredArgs = [
         'tunnel',
         '--no-autoupdate',
+        // HTTP/2 carries WebSockets and survives networks that advertise QUIC
+        // support but silently age out its UDP flow after the pre-check succeeds.
+        '--protocol', 'http2',
         '--url', `http://127.0.0.1:${port}`,
+    ];
+    const child = spawn(process.execPath, [
+        WATCHDOG_PATH,
+        String(process.pid),
+        binary.path,
+        ...cloudflaredArgs,
     ], { stdio: ['ignore', 'pipe', 'pipe'] });
     const exited = new Promise((resolve) => {
         child.once('exit', () => resolve());
@@ -85,6 +258,9 @@ export async function startTunnel(port, { autoInstall = true, probePath = '/', r
     const stop = () => stopPromise ?? (stopPromise = stopChild());
     return new Promise((resolve, reject) => {
         let tail = '';
+        let url;
+        let registered = false;
+        let readinessScheduled = false;
         let settled = false;
         const finish = (fn) => {
             if (settled) {
@@ -96,7 +272,7 @@ export async function startTunnel(port, { autoInstall = true, probePath = '/', r
         };
         const timer = setTimeout(() => {
             finish(() => {
-                void stop().then(() => reject(new Error('cloudflared did not report a tunnel hostname within '
+                void stop().then(() => reject(new Error('cloudflared did not establish a public route within '
                     + `${URL_TIMEOUT_MS / 1000}s. Check network egress to `
                     + 'Cloudflare, or run `cloudflared tunnel --url '
                     + `http://127.0.0.1:${port}` + '` by hand to see its output.')));
@@ -111,19 +287,23 @@ export async function startTunnel(port, { autoInstall = true, probePath = '/', r
             tail = (tail + text).slice(-LOG_TAIL_BYTES);
             // Search the accumulated tail so a URL split across stream chunks is not
             // missed. The tail is bounded and the URL appears near startup.
-            const match = QUICK_TUNNEL_URL.exec(tail);
-            if (match) {
-                const url = match[0];
-                finish(() => {
-                    const probeUrl = new URL(probePath, `${url}/`).toString();
+            url ?? (url = QUICK_TUNNEL_URL.exec(tail)?.[0]);
+            registered || (registered = tail.includes(REGISTERED_TUNNEL));
+            if (url && registered && !readinessScheduled) {
+                const registeredUrl = url;
+                readinessScheduled = true;
+                clearTimeout(timer);
+                setTimeout(() => finish(() => {
+                    const probeUrl = new URL(probePath, `${registeredUrl}/`).toString();
                     void waitUntilRouted(probeUrl, {
                         isRunning: () => child.exitCode === null
                             && child.signalCode === null,
                         pollMs: readyPollMs,
+                        probe,
                         timeoutMs: readyTimeoutMs,
-                    }).then((ready) => {
+                    }).then(({ ready, reason }) => {
                         if (ready) {
-                            resolve({ url, ready, stop, binary });
+                            resolve({ url: registeredUrl, ready, stop, binary });
                             return;
                         }
                         if (child.exitCode !== null || child.signalCode !== null) {
@@ -131,16 +311,13 @@ export async function startTunnel(port, { autoInstall = true, probePath = '/', r
                                 + 'cloudflared output:\n' + tail));
                             return;
                         }
-                        LOGGER.warn({ url, tail }, 'tunnel still propagating; returning the live hostname');
-                        resolve({
-                            url,
-                            ready,
-                            cloudflaredLog: tail,
-                            stop,
-                            binary,
-                        });
+                        void stop().then(() => reject(new HostnameNotRoutedError('Cloudflare assigned a hostname, but the public viewer did '
+                            + `not become reachable within ${readyTimeoutMs / 1000}s. `
+                            + (reason ? `Last check: ${reason}. ` : '')
+                            + 'The unverified hostname was closed instead of being '
+                            + 'shared.', tail)));
                     });
-                });
+                }), registeredSettleMs);
             }
         };
         child.stdout?.on('data', onChunk);