@reclaimprotocol/agent 0.1.25 → 0.1.27

package/lib/old/tools/session-logs.js

@@ -0,0 +1,310 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { defineTool } from "../../mcp/server.js";
+import { findProjectRoot } from "../../paths.js";
+/** The log-stream service caps a page at 1000 entries however large a
+ *  `limit` asks for, so paging is the only way past it. */
+const MAX_PAGE = 1000;
+/** Inline default. Small enough to stay readable in a tool result; a bigger
+ *  pull belongs in `saveTo`. */
+const DEFAULT_LIMIT = 200;
+/** Ceiling on a `saveTo` dump, so a chatty session can't page forever. */
+const DEFAULT_MAX_ENTRIES = 20000;
+export function sessionLogsTool(client) {
+    return defineTool({
+        name: 'session_logs',
+        description: 'Fetch the raw log entries the in-app SDK emitted during a '
+            + 'verification session, each with its event type (for example '
+            + 'REQUEST_MATCHED, CLAIM_CREATION_STARTED, or PROOF_GENERATED), '
+            + 'log level, and logger name. This is the data behind the '
+            + 'dashboard session-logs tab, and it is far more detailed than '
+            + 'session_analytics_logs, which returns only the coarse milestone '
+            + 'events. Use it to diagnose a session that stalled, matched '
+            + 'nothing, or produced no claim. Narrow the result with eventType, '
+            + 'logLevel, or contains; page through it with limit and offset; or '
+            + 'set saveTo to write every matching entry to an NDJSON file and '
+            + 'read that file with your own tools. Old-devtools mode only. You '
+            + 'must own the app the session belongs to, so call '
+            + 'reclaim_authenticate first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: {
+                    type: 'string',
+                    description: 'Id of the verification session to read log entries for.',
+                },
+                eventType: {
+                    type: 'string',
+                    description: 'Keep only entries that carry this exact event type, for '
+                        + 'example REQUEST_MATCHED or PROOF_GENERATION_FAILED_'
+                        + 'EXCEPTION. Most entries carry no event type at all, so '
+                        + 'prefer eventsOnly when you want the milestone timeline '
+                        + 'rather than guessing a name.',
+                },
+                eventsOnly: {
+                    type: 'boolean',
+                    description: 'Keep only entries that carry an event type, which gives you '
+                        + 'a compact milestone timeline for the session. This tool '
+                        + 'applies the filter after fetching, so it narrows what you '
+                        + 'read rather than what it fetches.',
+                },
+                logLevel: {
+                    type: 'string',
+                    enum: ['fine', 'config', 'info', 'warning', 'severe', 'unknown'],
+                    description: 'Lowest severity to include. Each value is hierarchical: '
+                        + '`fine` includes FINE, CONFIG, INFO, WARNING, and SEVERE; '
+                        + '`info` drops FINE and CONFIG; `severe` keeps only '
+                        + 'failures. Defaults to `fine`, which is wider than the '
+                        + 'backend default of `info`. The FINER and FINEST tiers '
+                        + 'contain PII, and this route rejects them.',
+                },
+                logType: {
+                    type: 'string',
+                    description: 'Exact client-side logger name, which the SDK calls `type` — '
+                        + 'for example reclaim_flutter_sdk.ClaimCreation. This is not '
+                        + 'the event type.',
+                },
+                contains: {
+                    type: 'string',
+                    description: 'Substring that an entry\'s log line must contain.',
+                },
+                providerId: {
+                    type: 'string',
+                    description: 'Keep only entries for this provider. A session can touch '
+                        + 'more than one provider, so this narrows within the '
+                        + 'session; it cannot search across sessions.',
+                },
+                deviceId: {
+                    type: 'string',
+                    description: 'Keep only entries for this device id, which is the claimant '
+                        + 'id.',
+                },
+                source: {
+                    type: 'string',
+                    description: 'Keep only entries from this client build. The source string '
+                        + 'carries the SDK, platform, and version, so it is the field '
+                        + 'to compare a working run against a broken one.',
+                },
+                startTime: {
+                    type: 'string',
+                    description: 'Lower bound, as an ISO-8601 timestamp. If you set neither '
+                        + 'bound, the backend searches only the last 3 days.',
+                },
+                endTime: {
+                    type: 'string',
+                    description: 'Upper bound, as an ISO-8601 timestamp.',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Log entries per page. Defaults to ${DEFAULT_LIMIT} and is `
+                        + `capped at ${MAX_PAGE}. Ignored when you set saveTo.`,
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Entries to skip, counting back from the newest match. '
+                        + 'Ignored when you set saveTo.',
+                },
+                saveTo: {
+                    type: 'string',
+                    description: 'Path to write every matching entry to, as NDJSON: one raw '
+                        + 'entry per line, oldest first. When you set this, the tool '
+                        + 'returns a summary instead of the entries. Relative paths '
+                        + 'resolve against the project root. Use it when a session '
+                        + 'has more entries than you want to read inline.',
+                },
+                maxEntries: {
+                    type: 'number',
+                    description: 'Maximum entries a saveTo dump collects. Defaults to '
+                        + `${DEFAULT_MAX_ENTRIES}.`,
+                },
+            },
+            required: ['sessionId'],
+        },
+    }, async (args) => {
+        // The backend's own default is `info`, which silently hides every
+        // FINE and CONFIG entry — the ones that say what the interceptor
+        // actually saw. Debugging is the whole point of this tool, so widen
+        // the default here.
+        const query = {
+            logLevel: (args.logLevel ?? 'fine'),
+            logType: args.logType,
+            eventType: args.eventType,
+            providerId: args.providerId,
+            deviceId: args.deviceId,
+            source: args.source,
+            startTime: args.startTime,
+            endTime: args.endTime,
+            logLine: args.contains,
+        };
+        return args.saveTo
+            ? await dump(client, args, query, args.saveTo)
+            : await page(client, args, query);
+    });
+}
+/** One page, returned inline. */
+async function page(client, args, query) {
+    const limit = clampLimit(args.limit ?? DEFAULT_LIMIT);
+    const offset = Math.max(args.offset ?? 0, 0);
+    const res = await client.getSessionLogs(args.sessionId, {
+        ...query,
+        limit,
+        offset,
+        includeCount: true,
+    });
+    // Newest-first off the wire; a debugger reads a session forwards.
+    const chronological = [...res.data].reverse();
+    const entries = args.eventsOnly
+        ? chronological.filter(hasEvent)
+        : chronological;
+    const fetched = res.data.length;
+    const total = res.totalCount;
+    return {
+        ...summarize(args, res.failedRegions, entries, total),
+        page: {
+            limit,
+            offset,
+            fetched,
+            ...(args.eventsOnly ? { keptWithEvent: entries.length } : {}),
+            hasMore: total === undefined
+                ? fetched === limit
+                : offset + fetched < total,
+            nextOffset: offset + fetched,
+        },
+        entries: compact(entries),
+    };
+}
+/** Every match, paged out to an NDJSON file. */
+async function dump(client, args, query, saveTo) {
+    const maxEntries = Math.max(args.maxEntries ?? DEFAULT_MAX_ENTRIES, 1);
+    const all = [];
+    const failedRegions = new Set();
+    let total;
+    let offset = 0;
+    while (all.length < maxEntries) {
+        const res = await client.getSessionLogs(args.sessionId, {
+            ...query,
+            limit: Math.min(MAX_PAGE, maxEntries - all.length),
+            offset,
+            // Only the first page pays for the count; it does not move.
+            includeCount: offset === 0,
+        });
+        for (const region of res.failedRegions ?? []) {
+            failedRegions.add(region);
+        }
+        if (offset === 0) {
+            total = res.totalCount;
+        }
+        all.push(...res.data);
+        offset += res.data.length;
+        // A short page means the match set is exhausted.
+        if (!res.data.length || res.data.length < MAX_PAGE) {
+            break;
+        }
+        if (total !== undefined && offset >= total) {
+            break;
+        }
+    }
+    all.reverse();
+    const entries = args.eventsOnly ? all.filter(hasEvent) : all;
+    const path = isAbsolute(saveTo)
+        ? saveTo
+        : join(findProjectRoot(process.cwd()), saveTo);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, entries.map(e => JSON.stringify(e)).join('\n') + '\n');
+    return {
+        ...summarize(args, [...failedRegions], entries, total),
+        file: {
+            path,
+            format: 'ndjson',
+            entries: entries.length,
+            order: 'oldest first',
+            note: 'Each line holds one raw log entry with all of its columns: '
+                + 'timestamp, log_level, event_type, log_type, log_line, '
+                + 'session_id, app_id, provider_id, device_id, source, and '
+                + 'metadata.',
+            truncated: entries.length >= maxEntries
+                ? `Stopped at maxEntries=${maxEntries}. Narrow the filters, or `
+                    + 'raise the limit.'
+                : undefined,
+        },
+    };
+}
+/** The header both modes share: what was asked for, what came back, and the
+ *  event-type histogram — usually enough on its own to see where a session
+ *  died. */
+function summarize(args, failedRegions, entries, total) {
+    const events = {};
+    for (const entry of entries) {
+        if (entry.event_type) {
+            events[entry.event_type] = (events[entry.event_type] ?? 0) + 1;
+        }
+    }
+    return {
+        sessionId: args.sessionId,
+        context: contextOf(entries),
+        totalMatching: total,
+        span: entries.length
+            ? {
+                from: entries[0].timestamp,
+                to: entries[entries.length - 1].timestamp,
+            }
+            : undefined,
+        eventTypes: Object.keys(events).length ? events : undefined,
+        ...(failedRegions?.length
+            ? {
+                warning: 'The log-stream query failed in region '
+                    + `${failedRegions.join(', ')}, so this result is incomplete.`,
+            }
+            : {}),
+        ...(entries.length
+            ? {}
+            : {
+                hint: 'No entries matched. Check these causes in order: the '
+                    + 'search window defaults to the last 3 days, so pass startTime '
+                    + 'and endTime for an older session; the backend deletes entries '
+                    + 'after 30 days; the backend picks which regions to query from '
+                    + 'the analytics table, so a session that never recorded an '
+                    + 'analytics event reads as empty here even when entries exist; '
+                    + 'or the filters are too narrow. Cross-check with '
+                    + 'session_analytics_logs.',
+            }),
+    };
+}
+/** Fields that are identical on every entry, hoisted out so they are not
+ *  repeated hundreds of times. */
+function contextOf(entries) {
+    const uniq = (pick) => {
+        const set = new Set(entries.map(pick).filter(Boolean));
+        return [...set];
+    };
+    const one = (values) => (values.length === 1 ? values[0] : values);
+    return entries.length
+        ? {
+            appId: one(uniq(e => e.app_id)),
+            providerId: one(uniq(e => e.provider_id)),
+            deviceId: one(uniq(e => e.device_id)),
+            source: one(uniq(e => e.source)),
+        }
+        : undefined;
+}
+function compact(entries) {
+    const devices = new Set(entries.map(e => e.device_id));
+    const sources = new Set(entries.map(e => e.source));
+    return entries.map(e => ({
+        ts: e.timestamp,
+        level: e.log_level,
+        ...(e.event_type ? { event: e.event_type } : {}),
+        logger: e.log_type,
+        line: e.log_line,
+        // Only worth repeating per entry once the page actually mixes them.
+        ...(devices.size > 1 ? { device: e.device_id } : {}),
+        ...(sources.size > 1 ? { source: e.source } : {}),
+        ...(e.metadata && e.metadata !== '{}' ? { metadata: e.metadata } : {}),
+    }));
+}
+function hasEvent(entry) {
+    return !!entry.event_type;
+}
+function clampLimit(limit) {
+    return Math.min(Math.max(Math.trunc(limit), 1), MAX_PAGE);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.25",
+	"version": "0.1.27",
 	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -83,7 +83,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.0.8",
-		"@reclaimprotocol/client": "0.1.25",
+		"@reclaimprotocol/client": "0.1.27",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/SKILL.builder.md

@@ -49,6 +49,22 @@ immediately with a `code` and `attachUrl` — it does NOT poll.
 The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs
 (`RECLAIM_API_TOKEN` in the server env overrides it).
 
+<!-- topic: devtools-migration -->
+## Import providers from devtools
+
+Use these operations only when the developer is migrating an existing legacy
+integration. Prefer Builder for new integrations.
+
+### Import from devtools
+
+1. Get the target `orgId` with `list_orgs`.
+2. Ask the developer for the legacy provider UUID.
+3. Call `import_devtools_provider(orgId, providerId)`.
+4. Use the returned provider UUID for all Builder operations. Import preserves
+   the UUID and latest legacy semantic version. It claims an anonymous catalog
+   seed idempotently, but never moves a provider from another Builder org. The
+   server reads the public devtools API; no legacy token is required.
+
 <!-- topic: browser -->
 <!-- common: browser -->
 

package/skill/SKILL.old.md

@@ -37,8 +37,9 @@ workflow — the narrow `authenticate_builder` / `list_builder_organizations`
 exception exists only to allocate Builder-hosted authoring browsers.
 `get_me_providers` is the only provider-listing tool here.
 
-**Diagnosing a session:** `session_analytics_logs` fetches a verification
-session's analytics logs by id (matches, claims, failures).
+**Diagnosing a session:** `session_analytics_logs` returns a session's
+milestone events; `session_logs` returns the log entries the SDK itself
+emitted. Read both from topic `troubleshooting`.
 
 <!-- topic: auth -->
 ## Getting authenticated
@@ -357,6 +358,31 @@ breaks the page, and it's the smallest change. Only if that doesn't help, turn
 interception off entirely (`injectionType: NONE`, or omit
 `interceptorOptions`). Full checklist and remedies: topic `interception`.
 
+**A session stalled, matched nothing, or produced no claim.** Read it with
+two tools, coarse to fine. `session_analytics_logs` returns the milestone
+events for a session id — SESSION_STARTED, PROOF_GENERATION_FAILED, and so on
+— which tells you how far the session got. `session_logs` returns the log
+entries the SDK emitted, each with its event type, log level, and logger name,
+which tells you why it stopped: the request it intercepted, the match or
+redaction that failed, and what the attestor answered. Work through it in this
+order:
+
+1. Call `session_analytics_logs({ sessionId })` to place the failure on the
+   timeline.
+2. Call `session_logs({ sessionId, eventsOnly: true })` for the same timeline
+   at entry level, then drop `eventsOnly` and add `contains` or `eventType` to
+   read around the entry that failed.
+3. To compare a working run against a broken one, filter by `source` — it
+   carries the SDK, platform, and version, which is usually the variable that
+   differs.
+
+Two defaults decide whether you see anything: the backend searches only the
+last 3 days unless you pass `startTime` and `endTime`, and it deletes entries
+after 30 days. An empty result is more often one of those than a genuinely
+silent session, so read the `hint` the tool returns before concluding
+anything. When a session is too large to read inline, pass `saveTo` to write
+every entry to an NDJSON file and grep that file instead.
+
 **Proof failures / attestor errors** → topic `prove`.
 **Browser won't launch or attach** → topic `browser`.
 **Missing signing key** → topic `credentials`.

package/skill/builder-mode.md

@@ -9,9 +9,9 @@ call a provider a "verification."**
 
 **Read the guide before authoring.** `how_it_works({ topic })` serves it, one
 topic at a time — call `how_it_works({})` for the topic index. Topics:
-`overview`, `auth`, `browser`, `capture`, `draft`, `params`, `prove`, `publish`,
-`discover`, `user-script`, `interception`, `hash-validation`, `credentials`,
-`never-do`, `troubleshooting`.
+`overview`, `auth`, `devtools-migration`, `browser`, `capture`, `draft`,
+`params`, `prove`, `publish`, `discover`, `user-script`, `interception`,
+`hash-validation`, `credentials`, `never-do`, `troubleshooting`.
 
 **Authentication:** try `get_me` first. On 401, `authenticate({})` returns a
 device-pairing `code` + `attachUrl` — give the user the URL, then poll

package/skill/old-mode.md

@@ -52,8 +52,10 @@ and the proof binds to nobody — find an auth-bound request instead.
 Values the CONSUMER supplies at verification time use `{{context_<name>}}` —
 this backend does NOT support the builder's dotted `{{context.<name>}}` form.
 
-**Diagnosing a session:** `session_analytics_logs` fetches a verification
-session's analytics logs by id (matches, claims, failures).
+**Diagnosing a session:** `session_analytics_logs` returns a session's
+milestone events; `session_logs` returns the log entries the SDK emitted, each
+with its event type — that is where a failed match, redaction, or claim shows
+up. Both take a `sessionId`; see topic `troubleshooting` for how to read them.
 
 **Backend mode:** the BUILDER backend (generated API tools, orgs, verification
 sessions, public review) is one switch away. `get_devtools_mode` reports the

package/src/live/tunnel.ts

@@ -26,40 +26,21 @@ import { type CloudflaredBinary, resolveCloudflared } from './cloudflared.ts'
 const URL_TIMEOUT_MS = 30_000
 /** After the hostname is printed, Cloudflare needs a moment before the edge
  *  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. */
+ *  URL that errors. */
 const READY_TIMEOUT_MS = 20_000
 const READY_POLL_MS = 1_000
+const STOP_TIMEOUT_MS = 5_000
 
 /** `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
 
-/**
- * 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
 
 export interface Tunnel {
 	/** The public HTTPS origin Cloudflare assigned. */
 	url: string
-	/** 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. */
@@ -69,37 +50,43 @@ export interface Tunnel {
 /**
  * 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.
+ * A cloudflared "Registered tunnel connection" log is not enough: Cloudflare
+ * can report one while the assigned hostname still returns DNS NXDOMAIN. The
+ * public viewer itself must return a successful response.
  */
 async function waitUntilRouted(
 	url: string,
-	isRegistered: () => boolean,
+	{
+		isRunning,
+		pollMs,
+		timeoutMs,
+	}: {
+		isRunning: () => boolean
+		pollMs: number
+		timeoutMs: number
+	},
 ): Promise<boolean> {
-	const deadline = Date.now() + READY_TIMEOUT_MS
+	const deadline = Date.now() + timeoutMs
 	while(Date.now() < deadline) {
-		if(isRegistered()) {
-			return true
+		if(!isRunning()) {
+			return false
 		}
 
 		try {
-			await fetch(url, {
+			const response = await fetch(url, {
 				method: 'GET',
 				redirect: 'manual',
-				signal: AbortSignal.timeout(READY_POLL_MS * 2),
+				signal: AbortSignal.timeout(pollMs * 2),
 			})
-			return true
-		} catch{
-			await new Promise((r) => setTimeout(r, READY_POLL_MS))
-		}
+			if(response.ok) {
+				return true
+			}
+		} catch{}
+
+		await new Promise((r) => setTimeout(r, pollMs))
 	}
 
-	return isRegistered()
+	return false
 }
 
 /**
@@ -111,7 +98,20 @@ async function waitUntilRouted(
  */
 export async function startTunnel(
 	port: number,
-	{ autoInstall = true }: { autoInstall?: boolean } = {},
+	{
+		autoInstall = true,
+		probePath = '/',
+		readyPollMs = READY_POLL_MS,
+		readyTimeoutMs = READY_TIMEOUT_MS,
+	}: {
+		autoInstall?: boolean
+		/** Public path that must answer before the tunnel is returned. */
+		probePath?: string
+		/** Test-only timing override. */
+		readyPollMs?: number
+		/** Test-only timing override. */
+		readyTimeoutMs?: number
+	} = {},
 ): Promise<Tunnel> {
 	// Resolves an existing cloudflared, or fetches one on first use. Throws
 	// with an actionable message when neither is possible.
@@ -121,25 +121,14 @@ export async function startTunnel(
 		'--no-autoupdate',
 		'--url', `http://127.0.0.1:${port}`,
 	], { stdio: ['ignore', 'pipe', 'pipe'] })
+	const exited = new Promise<void>((resolve) => {
+		child.once('exit', () => resolve())
+	})
 
-	const stop = async() => {
-		if(!child.killed) {
-			child.kill('SIGTERM')
-		}
-	}
+	let stopPromise: Promise<void> | undefined
+	const stop = () => stopPromise ??= stopChild()
 
 	return new Promise<Tunnel>((resolve, reject) => {
-		const timer = setTimeout(() => {
-			void stop()
-			reject(new Error(
-				'cloudflared did not report a tunnel hostname 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.',
-			))
-		}, URL_TIMEOUT_MS)
-
-		let registered = false
 		let tail = ''
 		let settled = false
 		const finish = (fn: () => void) => {
@@ -152,30 +141,50 @@ export async function startTunnel(
 			fn()
 		}
 
+		const timer = setTimeout(() => {
+			finish(() => {
+				void stop().then(() => reject(new Error(
+					'cloudflared did not report a tunnel hostname 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.',
+				)))
+			})
+		}, URL_TIMEOUT_MS)
+
 		// cloudflared logs the assigned hostname to stderr, not stdout. Watch
 		// both so a future version that switches streams still works.
 		const onChunk = (chunk: Buffer) => {
 			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.
+			// Keep watching after the hostname so a readiness failure can include
+			// cloudflared's account of what happened.
 			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, () => registered).then((ready) => {
+					const probeUrl = new URL(probePath, `${url}/`).toString()
+					void waitUntilRouted(probeUrl, {
+						isRunning: () => child.exitCode === null
+							&& child.signalCode === null,
+						pollMs: readyPollMs,
+						timeoutMs: readyTimeoutMs,
+					}).then(async(ready) => {
 						if(ready) {
-							resolve({ url, ready, stop, binary })
+							resolve({ url, stop, binary })
 							return
 						}
 
+						await stop()
 						LOGGER.warn({ url, tail },
-							'tunnel never registered with an edge; returning anyway')
-						resolve({ url, ready, stop, binary, diagnostics: tail })
+							'tunnel public URL never became reachable')
+						reject(new Error(
+							'cloudflared created a hostname, but the public viewer did '
+							+ `not become reachable within ${readyTimeoutMs / 1000}s. `
+							+ 'Retry share_browser_view. cloudflared output:\n'
+							+ tail,
+						))
 					})
 				})
 			}
@@ -205,4 +214,27 @@ export async function startTunnel(
 			)))
 		})
 	})
+
+	async function stopChild() {
+		if(child.exitCode !== null || child.signalCode !== null) {
+			return
+		}
+
+		let timeout: NodeJS.Timeout | undefined
+		const timedOut = new Promise<void>((resolve) => {
+			timeout = setTimeout(resolve, STOP_TIMEOUT_MS)
+		})
+		child.kill('SIGTERM')
+		await Promise.race([
+			exited,
+			timedOut,
+		])
+		clearTimeout(timeout)
+		if(child.exitCode !== null || child.signalCode !== null) {
+			return
+		}
+
+		child.kill('SIGKILL')
+		await exited
+	}
 }