@reclaimprotocol/agent 0.1.24 → 0.1.25

package/lib/cdp/container.js

@@ -0,0 +1,481 @@
+/**
+ * Run the Reclaim browser runtime in a container.
+ *
+ * This is the same image Popcorn serves for `builder` mode, run on the
+ * developer's own Docker instead of on quota. It brings its own Chromium and
+ * its own live view — a real VNC viewer with an IME, gesture handling and an
+ * OS-level pointer path — so nothing here renders anything. It starts the
+ * container, waits for it to mean it, and hands back the two URLs.
+ *
+ * Three ports exist inside; we publish two, and the distinction matters:
+ *
+ *  - **6080, the viewer.** Safe to put behind a tunnel, which is what
+ *    `share_browser_view` does.
+ *  - **9226, full CDP.** Unfiltered, unauthenticated browser control. Bound to
+ *    loopback and NEVER tunnelled: upstream's own warning is that exposing it
+ *    "would hand anyone control of the browser".
+ *  - **9222, restricted CDP.** Not published at all. Its allowlist is 19
+ *    methods with no `Runtime.*` and no `Network.*`, so it cannot drive the
+ *    authoring loop — verified against a running container.
+ */
+import { execFile } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { LOGGER } from "../logger.js";
+import { reclaimHomeDirPath } from "../paths.js";
+import { busySlots, claim, ownSlots, processAlive, release, } from "./claims.js";
+const execFileAsync = promisify(execFile);
+/**
+ * The pinned runtime image.
+ *
+ * A digest, not a tag. Upstream publishes 40-char git SHAs plus moving
+ * `main`/`latest` aliases and no semver at all, and its own docs say to
+ * "prefer immutable digests". Pinning one means an agent release cannot have
+ * the browser changed underneath it.
+ *
+ * Digest of `latest` as of 2026-08-22, built from popcorn-oss
+ * `4df751c25c7b329699033957b93f6486837e4acb`.
+ */
+export const BROWSER_RUNTIME_IMAGE = 'ghcr.io/reclaimprotocol/popcorn-oss/browser-runtime'
+    + '@sha256:6858c30a37886bc30d8f658e31aeb0bb253ad22eece16e4e41c8883345b399e1';
+/**
+ * The image is amd64-only and cannot be otherwise: the browser is Tilion
+ * Fortress, pinned by digest upstream, and Fortress publishes no arm64
+ * manifest. On Apple Silicon it therefore runs translated — which works under
+ * Docker Desktop's Rosetta and OrbStack, and crashes under QEMU. Pinning the
+ * platform is what stops Docker quietly trying to find an arm64 variant that
+ * does not exist.
+ */
+const PLATFORM = 'linux/amd64';
+/** Ports inside the container. */
+const VIEWER_PORT = 6080;
+const CDP_PORT = 9226;
+/**
+ * How many browsers may run at once.
+ *
+ * Each is about 2 GB of RAM, so this is a guard against a runaway rather than a
+ * capability. Sessions normally SHARE one: a slot is only added when another
+ * session is actively holding the previous one.
+ */
+const MAX_SLOTS = 4;
+/**
+ * Marks a container as ours and records which process owns it.
+ *
+ * The PID makes orphan cleanup safe. A container outlives its owner whenever a
+ * session is killed, so something has to remove it — but never one another
+ * session is still using. Whether the owning PID is alive answers that, and
+ * errs harmlessly: a recycled PID leaves a container behind rather than killing
+ * a live one.
+ */
+const OWNER_LABEL = 'org.reclaim.agent.owner-pid';
+/**
+ * Two ports nobody is using, guaranteed different from each other.
+ *
+ * A fixed port would give concurrent sessions the same container — the name
+ * derives from the viewer port — so session two would silently drive session
+ * one's browser.
+ *
+ * Both listeners are held open together and released together. Asking twice in
+ * sequence can return the same port, since the first is already closed by the
+ * time the second asks, and one port cannot carry both the viewer and CDP.
+ *
+ * Between releasing a port and Docker publishing it, another process can take
+ * it. That race is unavoidable, and losing it fails the `docker run` loudly
+ * rather than doing anything silent.
+ */
+async function freePortPair() {
+    const servers = [createServer(), createServer()];
+    try {
+        const ports = await Promise.all(servers.map(async (server) => {
+            await new Promise((resolve) => {
+                server.listen(0, '127.0.0.1', resolve);
+            });
+            return server.address().port;
+        }));
+        return { viewer: ports[0], cdp: ports[1] };
+    }
+    finally {
+        await Promise.all(servers.map((server) => {
+            return new Promise((resolve) => server.close(() => resolve()));
+        }));
+    }
+}
+/**
+ * Readiness deadline. The entrypoint gives Chromium 30s to put a window on the
+ * X display before failing, and a cold start measured 6.6s here with the geoip
+ * lookup disabled. 90s leaves room for a slow machine without hanging forever.
+ */
+const READY_TIMEOUT_MS = 90000;
+const READY_POLL_MS = 250;
+/**
+ * Where the container's Chromium profile lives on the host.
+ *
+ * Mounted, unlike the reference dev script, for two reasons. Provider authoring
+ * means signing in once and capturing an authenticated request, which a profile
+ * that dies with the container makes impossible. And the profile holds the
+ * persisted fingerprint identity — canvas/audio seed, timezone, locale — which
+ * upstream warns must stay stable, since "flipping any of them against the same
+ * cookie jar is itself a bot signal".
+ */
+export function containerProfileDir(slot = 0) {
+    // Slot 0 keeps the original path, so an existing profile — and the login in
+    // it — survives this change. Later slots get their own, because two
+    // Chromiums on one `user-data-dir` corrupt it silently.
+    const suffix = slot === 0 ? '' : `-${slot}`;
+    return join(reclaimHomeDirPath(), `browser-runtime-profile${suffix}`);
+}
+/** Docker CLI present AND its daemon reachable. */
+export async function dockerAvailable() {
+    try {
+        // `--format {{.Server.Version}}` talks to the daemon, so unlike
+        // `docker --version` it fails when Docker is installed but not running.
+        const { stdout } = await execFileAsync('docker', ['version', '--format', '{{.Server.Version}}'], { timeout: 15000 });
+        return stdout.trim().length > 0;
+    }
+    catch (err) {
+        LOGGER.debug({ err }, 'docker is unavailable');
+        return false;
+    }
+}
+/** Message for the case we cannot fix for them. */
+export function dockerMissingMessage() {
+    return 'Container mode needs Docker, and its daemon is not reachable. '
+        + 'Install Docker Desktop (https://docs.docker.com/get-started/get-docker/)'
+        + ' or OrbStack and start it, then retry. On Apple Silicon, enable Rosetta '
+        + 'for x86/amd64 emulation — the runtime image is amd64-only. '
+        + 'Or pick another browser: `dedicated` uses local Chrome, and `builder` '
+        + 'is a remote browser that comes with its own hosted live view.';
+}
+async function imagePresent(image) {
+    try {
+        await execFileAsync('docker', ['image', 'inspect', image], { timeout: 20000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Fetch the image. About 432 MB, so `startContainer` reports it happened. */
+async function pullImage(image) {
+    await execFileAsync('docker', ['pull', '--platform', PLATFORM, image], { timeout: 900000, maxBuffer: 1024 * 1024 * 8 });
+}
+/**
+ * The `docker run` argv.
+ *
+ * A pure function because every flag here is load bearing and none of it is
+ * obvious from the outside: which ports are loopback-only, that the image is
+ * digest-pinned, that the profile is mounted. Tests assert on this directly
+ * rather than trying to observe a running container.
+ */
+export function buildRunArgs(opts, image, name, profileDir) {
+    const args = [
+        'run', '--rm', '-d',
+        '--name', name,
+        '--platform', PLATFORM,
+        // Whose container this is, so an orphan can be told from a container
+        // another session is still driving.
+        '--label', `${OWNER_LABEL}=${process.pid}`,
+        // Loopback only. Both CDP proxies listen on 0.0.0.0 INSIDE the container,
+        // so what is reachable is entirely down to this mapping.
+        '-p', `127.0.0.1:${opts.viewerPort}:${VIEWER_PORT}`,
+        '-p', `127.0.0.1:${opts.cdpPort}:${CDP_PORT}`,
+        // Chromium on Docker's default 64 MB /dev/shm is a crash waiting for a
+        // heavy page. The image README and the upstream Helm chart both give it
+        // 1-2 GiB; only the dev script leaves the default.
+        '--shm-size=1g',
+        // The runtime looks up its own geolocation at boot, twice, with an 8s
+        // timeout each — up to 16s added to every cold start. We are not
+        // impersonating a locale (that is what `builder` mode's country routing is
+        // for), so skip it. Measured: 6.6s to ready with this off.
+        '-e', 'CLOAK_GEOIP=false',
+        // Cookies, localStorage and the persisted fingerprint identity. Without
+        // it, signing in once — the entire point of authoring — cannot survive a
+        // restart.
+        '-v', `${profileDir}:/home/kernel/user-data`,
+    ];
+    if (opts.width) {
+        args.push('-e', `WIDTH=${opts.width}`);
+    }
+    if (opts.height) {
+        args.push('-e', `HEIGHT=${opts.height}`);
+    }
+    if (opts.url) {
+        args.push('-e', `APP_URL=${opts.url}`);
+    }
+    args.push(image);
+    return args;
+}
+/**
+ * Start a browser container and wait until it is actually serving.
+ *
+ * Ports are allocated per call, so concurrent sessions never land on the same
+ * container. Pass `viewerPort` to pin one — re-attaching with the same port
+ * reuses the container that is already there.
+ */
+export async function startContainer(options = {}) {
+    // Containers whose session died without cleaning up, cleared before we look
+    // for one to adopt. Deliberately here rather than at server startup: a
+    // short-lived server exits before a fire-and-forget reap finishes, and nobody
+    // who never uses container mode should pay for a `docker ps` at launch.
+    await reapOrphanedContainers();
+    const image = options.image ?? BROWSER_RUNTIME_IMAGE;
+    const slot = await pickSlot();
+    const name = containerName(slot);
+    const token = claim(name);
+    // Adopt a container that is already serving on this slot. This is the common
+    // case for one developer working across sessions: the browser, and whatever
+    // they signed into, is still there.
+    const adopted = await adopt(name);
+    if (adopted) {
+        LOGGER.info({ name }, 'adopted the browser container already running');
+        return describe(adopted, name, false, slot, token);
+    }
+    // Anything left under this name is wreckage — the slot has no live claimant.
+    if (await inspectContainer(name)) {
+        LOGGER.info({ name }, 'removing a container that is no longer serving');
+        await execFileAsync('docker', ['rm', '-f', name], { timeout: 60000 })
+            .catch(() => { });
+    }
+    const ports = await freePortPair();
+    const opts = {
+        ...options,
+        viewerPort: options.viewerPort ?? ports.viewer,
+        cdpPort: options.cdpPort ?? ports.cdp,
+    };
+    const profileDir = containerProfileDir(slot);
+    mkdirSync(profileDir, { recursive: true });
+    const pulled = !await imagePresent(image);
+    if (pulled) {
+        LOGGER.info({ image }, 'pulling the browser runtime image');
+        await pullImage(image);
+    }
+    await execFileAsync('docker', buildRunArgs(opts, image, name, profileDir), { timeout: 120000 });
+    try {
+        await waitUntilServing(opts.cdpPort);
+    }
+    catch (err) {
+        await captureLogs(name);
+        release(name, token);
+        await stopContainer(name);
+        throw err;
+    }
+    return describe(opts, name, pulled, slot, token);
+}
+/** `reclaim-browser-0`, `-1`, … — one name per slot, so a slot is findable. */
+function containerName(slot) {
+    return `reclaim-browser-${slot}`;
+}
+/**
+ * A slot this session may use.
+ *
+ * Prefers one we ALREADY hold, so re-attaching within a session adopts the
+ * browser it is already running instead of paying 2 GB and twenty seconds for a
+ * second one. Then the lowest slot nobody holds. A new slot only appears when
+ * ANOTHER session is actively using the earlier ones, because two containers on
+ * one profile would corrupt it.
+ */
+async function pickSlot() {
+    const held = ownSlots();
+    for (let slot = 0; slot < MAX_SLOTS; slot++) {
+        if (held.has(containerName(slot))) {
+            return slot;
+        }
+    }
+    const busy = busySlots();
+    for (let slot = 0; slot < MAX_SLOTS; slot++) {
+        if (!busy.has(containerName(slot))) {
+            return slot;
+        }
+    }
+    throw new Error(`All ${MAX_SLOTS} browser containers are in use by other sessions, which `
+        + 'is as many as this runs at once — each costs about 2 GB of RAM. Close '
+        + 'one of those sessions, or attach with mode "dedicated" to use local '
+        + 'Chrome instead.');
+}
+/**
+ * The ports a running container publishes, or undefined when there is nothing
+ * healthy to adopt.
+ *
+ * Adoption has to DISCOVER the ports rather than allocate them: the container
+ * was started by a previous session that chose its own.
+ */
+async function adopt(name) {
+    if (await inspectContainer(name) !== 'running') {
+        return undefined;
+    }
+    let mapped = '';
+    try {
+        const { stdout } = await execFileAsync('docker', ['port', name], { timeout: 20000 });
+        mapped = stdout;
+    }
+    catch {
+        return undefined;
+    }
+    // Lines look like `6080/tcp -> 127.0.0.1:49987`.
+    const portFor = (containerPort) => {
+        const line = mapped.split('\n')
+            .find((l) => l.startsWith(`${containerPort}/tcp`));
+        const host = line?.split(':').pop()?.trim();
+        return host ? Number(host) : undefined;
+    };
+    const viewerPort = portFor(VIEWER_PORT);
+    const cdpPort = portFor(CDP_PORT);
+    if (!viewerPort || !cdpPort || !await isServing(cdpPort)) {
+        return undefined;
+    }
+    return { viewerPort, cdpPort };
+}
+/** Read the container's CDP websocket and assemble the handle. */
+async function describe(opts, name, pulled, slot, token) {
+    const version = await fetch(`http://127.0.0.1:${opts.cdpPort}/json/version`)
+        .then((res) => res.json());
+    if (!version.webSocketDebuggerUrl) {
+        await stopContainer(name);
+        throw new Error('The browser container is serving but reported no CDP websocket.');
+    }
+    return {
+        viewerUrl: `http://127.0.0.1:${opts.viewerPort}/liveview.html?magnify=1`,
+        cdpUrl: version.webSocketDebuggerUrl,
+        viewerPort: opts.viewerPort,
+        name,
+        pulled,
+        slot,
+        // Stopping is really "I am done with it". The container only goes when
+        // this was the last session holding the slot; otherwise it keeps serving
+        // whoever else is using it.
+        stop: async () => {
+            if (release(name, token)) {
+                await stopContainer(name);
+                return;
+            }
+            LOGGER.info({ name }, 'left the container running for another session');
+        },
+    };
+}
+/** Stop a container. `--rm` means stopping it also removes it. Best effort:
+ *  teardown must not throw on the way out. */
+async function stopContainer(name) {
+    try {
+        await execFileAsync('docker', ['stop', '-t', '2', name], { timeout: 60000 });
+    }
+    catch (err) {
+        // Already gone is the outcome we wanted, not a problem to report.
+        const message = err instanceof Error ? err.message : String(err);
+        if (/No such container/i.test(message)) {
+            LOGGER.debug({ name }, 'container was already stopped');
+            return;
+        }
+        LOGGER.warn({ err, name }, 'could not stop the browser container');
+    }
+}
+/** Docker's state for a container, or undefined when there is no such name. */
+async function inspectContainer(name) {
+    try {
+        const { stdout } = await execFileAsync('docker', ['inspect', '--format', '{{.State.Status}}', name], { timeout: 20000 });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One shot of the readiness check, for deciding whether to reuse. */
+async function isServing(cdpPort) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${cdpPort}/json/version`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wait until the runtime is serving, not merely listening.
+ *
+ * The proxy binds its ports early and answers `503 app is not ready` on EVERY
+ * route until the entrypoint has seen a Chromium window and touched
+ * `/tmp/minimal-vnc-ready`. So a plain "did the socket accept" check passes
+ * while there is no browser — which is exactly the trap the reference script
+ * falls into, polling with `curl -sS` and no `-f`. Requiring a 2xx is the whole
+ * point.
+ */
+async function waitUntilServing(cdpPort) {
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    let lastStatus = 'no response';
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`http://127.0.0.1:${cdpPort}/json/version`, {
+                signal: AbortSignal.timeout(2000),
+            });
+            if (res.ok) {
+                return;
+            }
+            lastStatus = `HTTP ${res.status}`;
+        }
+        catch (err) {
+            lastStatus = err instanceof Error ? err.message : String(err);
+        }
+        await new Promise((resolve) => setTimeout(resolve, READY_POLL_MS));
+    }
+    throw new Error('The browser container never became ready within '
+        + `${READY_TIMEOUT_MS / 1000}s (last: ${lastStatus}). On Apple Silicon `
+        + 'this usually means x86 emulation is unavailable — enable Rosetta in '
+        + 'Docker Desktop, or use OrbStack.');
+}
+/** Log the container's own account of a failed start, which is where the
+ *  reason lives (a SIGTRAP under QEMU, say). */
+async function captureLogs(name) {
+    try {
+        const { stdout, stderr } = await execFileAsync('docker', ['logs', '--tail', '40', name], { timeout: 20000 });
+        LOGGER.warn({ name, logs: `${stdout}\n${stderr}`.trim().slice(-4000) }, 'browser container failed to start');
+    }
+    catch (err) {
+        LOGGER.debug({ err }, 'could not read the container logs');
+    }
+}
+/**
+ * Remove containers whose owning process is gone.
+ *
+ * Shutdown cleanup covers an orderly exit, but a SIGKILL or a crash runs
+ * nothing — and a 1.3 GB container with a live browser in it should not outlive
+ * the session that made it. Reaping at startup catches those, and the owner-PID
+ * label keeps it safe: a container whose owner still runs belongs to another
+ * session and is left alone.
+ */
+export async function reapOrphanedContainers() {
+    let listed = '';
+    try {
+        const { stdout } = await execFileAsync('docker', [
+            'ps', '--filter', `label=${OWNER_LABEL}`,
+            '--format', `{{.Names}} {{.Label "${OWNER_LABEL}"}}`,
+        ], { timeout: 20000 });
+        listed = stdout;
+    }
+    catch {
+        // No Docker, or no daemon. Nothing to reap and nothing to report.
+        return [];
+    }
+    const reaped = [];
+    for (const line of listed.split('\n')) {
+        const [name, pid] = line.trim().split(/\s+/);
+        if (!name || !pid) {
+            continue;
+        }
+        if (processAlive(Number(pid))) {
+            continue;
+        }
+        try {
+            await execFileAsync('docker', ['rm', '-f', name], { timeout: 60000 });
+            reaped.push(name);
+            LOGGER.info({ name, pid }, 'removed an orphaned browser container');
+        }
+        catch (err) {
+            // Someone else may have removed it first. Not worth failing a start.
+            LOGGER.debug({ err, name }, 'could not remove an orphan');
+        }
+    }
+    return reaped;
+}

package/lib/live/tunnel.d.ts

@@ -2,10 +2,13 @@ import { type CloudflaredBinary } from './cloudflared.ts';
 export interface Tunnel {
     /** The public HTTPS origin Cloudflare assigned. */
     url: string;
-    /** Whether the edge answered before {@link READY_TIMEOUT_MS} elapsed. False
-     *  means the tunnel is probably still propagating rather than broken — tell
-     *  the viewer to retry rather than treating the share as failed. */
+    /** Whether the tunnel was carrying traffic before {@link READY_TIMEOUT_MS}
+     *  elapsed. False means it may still be propagating rather than broken — say
+     *  so rather than treating the share as failed. */
     ready: boolean;
+    /** cloudflared's own last words, for when `ready` is false and someone has
+     *  to work out why. Absent when the tunnel came up normally. */
+    diagnostics?: string;
     /** Terminate the tunnel. Safe to call more than once. */
     stop: () => Promise<void>;
     /** Which cloudflared ran, and whether we had to fetch it. */

package/lib/live/tunnel.js

@@ -1,15 +1,22 @@
 /**
- * Public HTTPS front door for the local live-view server, via a `cloudflared`
- * quick tunnel.
+ * Public HTTPS front door for a local port, via a `cloudflared` quick tunnel.
  *
  * A quick tunnel needs no Cloudflare account and no DNS: `cloudflared` dials
  * out, Cloudflare hands back a throwaway `*.trycloudflare.com` hostname, and
  * traffic arrives on the loopback port we pass in. That is the whole reason it
  * is used here — the developer's machine keeps no inbound port open.
  *
- * The tunnel itself carries NO authorization. Anyone holding the hostname can
- * reach the local server, so the server is the thing that must authenticate
- * (see `viewer.ts`, which puts an unguessable token in every path).
+ * **The hostname IS the secret, and it is the only one.** The tunnel carries no
+ * authorization of its own, and the browser runtime's viewer behind it has no
+ * login either — so whoever learns the URL has the browser. Cloudflare's
+ * hostnames are randomly generated, which is what makes that tolerable for a
+ * short, deliberate hand-off, and `stop_browser_view` is how it ends.
+ *
+ * That is weaker than what this file used to front. The agent's own screencast
+ * viewer added a 24-byte token to every path, so the hostname alone was not
+ * enough; the container's viewer has no equivalent. Callers must say plainly
+ * what the URL grants, and it must never front the container's CDP port, which
+ * is unauthenticated total control of the browser.
  */
 import { spawn } from 'node:child_process';
 import { LOGGER } from "../logger.js";
@@ -17,26 +24,49 @@ 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 a moment before the edge
- *  routes to it — measured at ~3s. Poll until it answers so the caller never
- *  hands out a URL that errors, but don't fail the share if it's slow. */
+ *  routes to it — measured at ~3s. Wait for it so the caller never hands out a
+ *  URL that errors, but don't fail the share if it's slow. */
 const READY_TIMEOUT_MS = 20000;
 const READY_POLL_MS = 1000;
 /** `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;
 /**
- * Poll the public origin until Cloudflare's edge routes to it. ANY HTTP
- * response counts, including a 404: the live-view server 404s unknown paths,
- * so a status code at all proves the hop is live.
+ * cloudflared says this once per edge connection it establishes, and until it
+ * does, the hostname resolves but routes nowhere.
+ *
+ * This is the signal to trust, because it is LOCAL. Asking whether we can fetch
+ * the public URL ourselves conflates two questions — is the tunnel up, and does
+ * this machine have egress to Cloudflare's edge — and reports "not ready" when
+ * only the second fails. Observed: a tunnel printed its hostname and registered
+ * nothing for 12s, which is indistinguishable from a blocked fetch unless you
+ * read cloudflared's own account of it.
+ */
+const REGISTERED = /Registered tunnel connection|connIndex=/i;
+/** Tail of cloudflared's log kept for error messages. */
+const LOG_TAIL_BYTES = 4096;
+/**
+ * Wait until the tunnel is actually carrying traffic.
+ *
+ * Two independent signals, either of which is proof:
+ *  - cloudflared reported an edge registration (see {@link REGISTERED}). Local,
+ *    so it works regardless of this machine's own egress.
+ *  - the public origin answered. ANY HTTP response counts, including a 404:
+ *    the live-view server 404s unknown paths, so a status code at all proves
+ *    the hop is live. Kept as a second opinion in case a cloudflared release
+ *    rewords its log.
  */
-async function waitUntilRouted(url) {
+async function waitUntilRouted(url, isRegistered) {
     const deadline = Date.now() + READY_TIMEOUT_MS;
     while (Date.now() < deadline) {
+        if (isRegistered()) {
+            return true;
+        }
         try {
             await fetch(url, {
                 method: 'GET',
                 redirect: 'manual',
-                signal: AbortSignal.timeout(READY_POLL_MS * 4),
+                signal: AbortSignal.timeout(READY_POLL_MS * 2),
             });
             return true;
         }
@@ -44,7 +74,7 @@ async function waitUntilRouted(url) {
             await new Promise((r) => setTimeout(r, READY_POLL_MS));
         }
     }
-    return false;
+    return isRegistered();
 }
 /**
  * Open a quick tunnel to `http://127.0.0.1:<port>` and resolve once
@@ -75,6 +105,8 @@ export async function startTunnel(port, { autoInstall = true } = {}) {
                 + 'or run `cloudflared tunnel --url http://127.0.0.1:'
                 + `${port}` + '` by hand to see its output.'));
         }, URL_TIMEOUT_MS);
+        let registered = false;
+        let tail = '';
         let settled = false;
         const finish = (fn) => {
             if (settled) {
@@ -88,15 +120,23 @@ export async function startTunnel(port, { autoInstall = true } = {}) {
         // both so a future version that switches streams still works.
         const onChunk = (chunk) => {
             const text = chunk.toString();
+            // Keep watching after the hostname: registration lands a beat later, and
+            // on a bad run it never lands at all, which is the case worth reporting.
+            tail = (tail + text).slice(-LOG_TAIL_BYTES);
+            if (REGISTERED.test(text)) {
+                registered = true;
+            }
             const match = QUICK_TUNNEL_URL.exec(text);
             if (match) {
                 const url = match[0];
                 finish(() => {
-                    void waitUntilRouted(url).then((ready) => {
-                        if (!ready) {
-                            LOGGER.warn({ url }, 'tunnel not routed yet; returning anyway');
+                    void waitUntilRouted(url, () => registered).then((ready) => {
+                        if (ready) {
+                            resolve({ url, ready, stop, binary });
+                            return;
                         }
-                        resolve({ url, ready, stop, binary });
+                        LOGGER.warn({ url, tail }, 'tunnel never registered with an edge; returning anyway');
+                        resolve({ url, ready, stop, binary, diagnostics: tail });
                     });
                 });
             }

package/lib/mcp/instructions.js

@@ -61,7 +61,8 @@ const SHARED_TOPIC_FILES = {
 const TOPIC_SUMMARIES = {
     'overview': 'Terminology, your stance, and the whole loop at a glance.',
     'auth': 'Signing in to the backend, and which token authorizes what.',
-    'browser': 'Choosing a browser source (local / remote / custom CDP), '
+    'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
+        + 'Docker, a remote Popcorn browser, or a custom CDP endpoint), '
         + 'geolocation, live view, and launch troubleshooting.',
     'capture': 'Tabs, login detection, driving the page, and picking an '
         + 'authenticated request to prove.',