@reclaimprotocol/agent 0.1.36 → 0.1.37

package/lib/cdp/launcher.js

@@ -1,9 +1,29 @@
+import { conflict, failedDependency, gatewayTimeout, preconditionFailed, } from '@hapi/boom';
+import assert from 'node:assert';
 import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync } from 'node:fs';
-import { homedir, platform } from 'node:os';
+import { existsSync, lstatSync, mkdirSync, readlinkSync, unlinkSync } from 'node:fs';
+import { homedir, hostname, platform } from 'node:os';
 import { join } from 'node:path';
 import { chromePath, localAppData } from "../consts.js";
+import { LOGGER } from "../logger.js";
 import { reclaimHomeDirPath } from "../paths.js";
+import { installChromeForTesting } from "./chrome-for-testing.js";
+/** How long a launched browser gets to answer CDP. A cold first start on a
+ *  slow disk, or Chrome for Testing's first run, can take well over 10s. */
+export const CDP_READY_TIMEOUT_MS = 30000;
+/** How much of the browser's stderr to keep for error messages. */
+const STDERR_TAIL_CHARS = 4096;
+/** The files Chrome uses on POSIX to claim a profile. `SingletonLock` is a
+ *  symlink to `<hostname>-<pid>`; the other two point at the IPC socket and a
+ *  random cookie, and are only meaningful while that process lives. */
+const SINGLETON_FILES = ['SingletonLock', 'SingletonSocket', 'SingletonCookie'];
+const DEFAULT_DEPENDENCIES = {
+    platform,
+    env: () => process.env,
+    chromePath,
+    findInstalled: () => findInstalledBrowsers(),
+    installChromeForTesting,
+};
 /**
  * Build the platform-specific list of Chromium-family binaries to probe.
  * Order matters: Chrome first, then Chromium, then Edge (Edge is
@@ -15,8 +35,8 @@ import { reclaimHomeDirPath } from "../paths.js";
  * without admin rights ("Install for me only"). Skipping this was the
  * #1 first-run failure observed in the field.
  */
-function browserCandidates() {
-    switch (platform()) {
+export function browserCandidates(os = platform()) {
+    switch (os) {
         case 'darwin':
             return [
                 '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
@@ -50,26 +70,105 @@ function browserCandidates() {
             return [];
     }
 }
+/** The candidates that exist on this machine, in preference order. */
+export function findInstalledBrowsers(candidates = browserCandidates()) {
+    return candidates.filter((c) => existsSync(c));
+}
 export function defaultProfileDir() {
     return join(reclaimHomeDirPath(), 'chrome-profile');
 }
 export function findChromeBinary() {
     const candidates = browserCandidates();
-    for (const c of candidates) {
-        if (existsSync(c)) {
-            return c;
-        }
+    const found = chromePath() ?? findInstalledBrowsers(candidates)[0];
+    if (found) {
+        return found;
     }
     throw new Error(`No Chromium-family browser found on ${platform()}. Tried:\n  ` +
         candidates.join('\n  ') +
         '\nSet RECLAIM_AGENT_CHROME_PATH to point at ' +
         'your chrome.exe / msedge.exe / chromium binary.');
 }
-export function launchChrome(opts) {
-    const binary = chromePath() ?? findChromeBinary();
-    if (!existsSync(opts.profileDir)) {
-        mkdirSync(opts.profileDir, { recursive: true });
+/**
+ * Why a visible browser cannot open here, or undefined when it can. Only
+ * Linux needs a display server named in the environment; an MCP server
+ * started outside the desktop session (a sandboxed agent, a service) often
+ * has neither variable, and Chrome then exits before CDP ever answers.
+ */
+export function missingDisplayReason(os = platform(), env = process.env) {
+    if (os !== 'linux' || env.WAYLAND_DISPLAY || env.DISPLAY) {
+        return undefined;
+    }
+    return 'No display: neither WAYLAND_DISPLAY nor DISPLAY is set in the '
+        + 'Reclaim MCP server\'s environment, so a visible browser cannot open. '
+        + 'Start the agent from the desktop session, or pass the variables to '
+        + 'the MCP server (for example DISPLAY=:0, or WAYLAND_DISPLAY=wayland-0 '
+        + 'with XDG_RUNTIME_DIR), then restart the agent.';
+}
+/**
+ * Launch a visible browser on this machine with the given profile, and wait
+ * until it answers CDP.
+ *
+ * Uses `RECLAIM_AGENT_CHROME_PATH` when set, else the first installed browser
+ * (Chrome, then Chromium, then Edge). When none is installed, or that one
+ * fails to start, it falls back to Chrome for Testing, downloaded once into
+ * `~/.reclaim/browsers`. A missing display fails fast instead: no browser can
+ * open without one, so a download would only waste time.
+ */
+export async function launchLocalBrowser(opts, dependencies = {}) {
+    const deps = { ...DEFAULT_DEPENDENCIES, ...dependencies };
+    const noDisplay = missingDisplayReason(deps.platform(), deps.env());
+    assert(!noDisplay, preconditionFailed(noDisplay));
+    // A live owner would make every launch below fail the same way, so refuse
+    // once with the reason instead of trying Chrome for Testing too.
+    releaseStaleProfileLock(opts.profileDir, deps.platform());
+    const override = deps.chromePath();
+    const preferred = override ?? deps.findInstalled()[0];
+    let fallbackReason = 'No Chrome, Chromium, or Edge is installed.';
+    if (preferred) {
+        try {
+            return {
+                binary: preferred,
+                source: override ? 'override' : 'installed',
+                process: await startChrome(preferred, opts),
+                downloaded: false,
+            };
+        }
+        catch (err) {
+            fallbackReason = errorMessage(err);
+            LOGGER.warn({ binary: preferred, reason: fallbackReason }, 'local browser failed to start; trying Chrome for Testing');
+        }
+    }
+    let cft;
+    try {
+        cft = await deps.installChromeForTesting();
+    }
+    catch (err) {
+        throw failedDependency(`${fallbackReason}\nChrome for Testing could not be installed into `
+            + `~/.reclaim/browsers: ${errorMessage(err)}`);
     }
+    try {
+        return {
+            binary: cft.executablePath,
+            source: 'chrome-for-testing',
+            process: await startChrome(cft.executablePath, opts),
+            downloaded: cft.downloaded,
+            fallbackReason,
+        };
+    }
+    catch (err) {
+        throw failedDependency(`${fallbackReason}\nChrome for Testing (${cft.executablePath}) also `
+            + `failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Spawn `binary` on `opts.profileDir` and wait for CDP. On failure the
+ * process is stopped and the error says why: it could not be spawned, it
+ * exited (with its code and the tail of its stderr), or it never answered.
+ */
+export async function startChrome(binary, opts) {
+    const timeoutMs = opts.timeoutMs ?? CDP_READY_TIMEOUT_MS;
+    mkdirSync(opts.profileDir, { recursive: true });
+    releaseStaleProfileLock(opts.profileDir);
     const args = [
         `--remote-debugging-port=${opts.port}`,
         `--user-data-dir=${opts.profileDir}`,
@@ -80,24 +179,145 @@ export function launchChrome(opts) {
         args.push('--headless=new', '--disable-gpu');
     }
     const child = spawn(binary, args, {
-        stdio: 'ignore',
+        stdio: ['ignore', 'ignore', 'pipe'],
         detached: false,
     });
-    return child;
-}
-export async function waitForCdpReady(port, timeoutMs = 10000) {
+    // Drained for the browser's whole life, not just until it is ready: a
+    // full pipe would block its writes.
+    let stderr = '';
+    child.stderr?.setEncoding('utf8');
+    child.stderr?.on('data', (chunk) => {
+        stderr = (stderr + chunk).slice(-STDERR_TAIL_CHARS);
+    });
+    let spawnError;
+    child.once('error', (err) => {
+        spawnError = err;
+    });
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
+        if (await cdpAnswers(opts.port)) {
+            return child;
+        }
+        if (spawnError) {
+            throw failedDependency(`Could not start ${binary}: ${spawnError.message}`);
+        }
+        if (child.exitCode !== null || child.signalCode !== null) {
+            throw failedDependency(`${binary} exited with ${child.exitCode !== null
+                ? `code ${child.exitCode}`
+                : `signal ${child.signalCode}`} before CDP answered on port `
+                + `${opts.port}.${stderrTail()}`);
+        }
+        await sleep(150);
+    }
+    await stopProcess(child);
+    throw gatewayTimeout(`${binary} did not answer CDP on port ${opts.port} within `
+        + `${timeoutMs}ms.${stderrTail()}`);
+    function stderrTail() {
+        const tail = stderr.trim();
+        return tail ? `\nBrowser stderr (last ${tail.length} chars):\n${tail}` : '';
+    }
+}
+/**
+ * Remove a dead browser's claim on `profileDir` so a new launch can take it.
+ *
+ * Chrome on POSIX claims a profile with `SingletonLock -> <hostname>-<pid>`.
+ * If that process is gone (a crash, a killed session) the links stay behind
+ * and the next launch hands off to the missing owner and exits. A lock whose
+ * PID is alive on this host belongs to a running browser, and is left alone:
+ * that browser must be closed first. A lock from another hostname is treated
+ * as stale: `~/.reclaim` is local, and a sandbox or container that changes the
+ * hostname between runs is the usual way to get one. Callers reach this only
+ * after nothing answered CDP on the port.
+ */
+export function releaseStaleProfileLock(profileDir, os = platform()) {
+    // Windows locks the profile with a plain file the OS releases on exit.
+    if (os === 'win32') {
+        return;
+    }
+    const target = readLink(join(profileDir, 'SingletonLock'));
+    const owner = target?.match(/^(.+)-(\d+)$/);
+    if (owner?.[1] === hostname() && processAlive(Number(owner[2]))) {
+        throw conflict(`The browser profile ${profileDir} is in use by a running browser `
+            + `(PID ${owner[2]}) that is not answering CDP on the requested port. `
+            + 'Close that browser window, then retry.');
+    }
+    const removed = SINGLETON_FILES.filter((name) => {
+        const path = join(profileDir, name);
+        if (readLink(path) === undefined) {
+            return false;
+        }
         try {
-            const res = await fetch(`http://127.0.0.1:${port}/json/version`);
-            if (res.ok) {
-                return;
-            }
+            unlinkSync(path);
+            return true;
+        }
+        catch (err) {
+            LOGGER.warn({ err, path }, 'could not remove a stale profile lock');
+            return false;
         }
-        catch {
-            // retry
+    });
+    if (removed.length) {
+        LOGGER.info({ profileDir, removed, owner: target }, 'removed a stale browser profile lock');
+    }
+}
+/**
+ * Wait until something answers CDP on `port`, polling every 150ms.
+ */
+export async function waitForCdpReady(port, timeoutMs = CDP_READY_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await cdpAnswers(port)) {
+            return;
         }
-        await new Promise((r) => setTimeout(r, 150));
+        await sleep(150);
     }
-    throw new Error(`Chrome CDP did not become ready on port ${port} within ${timeoutMs}ms`);
+    throw gatewayTimeout(`Chrome CDP did not become ready on port ${port} within ${timeoutMs}ms`);
+}
+/** A listener that accepts but never answers (a stale non-CDP service on the
+ *  port) fails the poll after 2s instead of outliving the launch deadline. */
+async function cdpAnswers(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** SIGTERM, then SIGKILL if it lingers, and wait for the exit either way, so
+ *  the profile lock is released before anything launches on it again. */
+async function stopProcess(child) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    const exited = new Promise((r) => child.once('exit', () => r()));
+    child.kill('SIGTERM');
+    const timer = setTimeout(() => child.kill('SIGKILL'), 3000);
+    await exited;
+    clearTimeout(timer);
+}
+function readLink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink() ? readlinkSync(path) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: it exists, it just belongs to someone else.
+        return err instanceof Error && 'code' in err && err.code === 'EPERM';
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
 }

package/lib/logger.js

@@ -1,8 +1,10 @@
 import pino, { stdTimeFunctions } from 'pino';
 import { LOG_LEVEL } from "./consts.js";
+// stderr, not pino's default stdout: the MCP server speaks JSON-RPC over
+// stdout, so a log line there corrupts the protocol stream.
 export const LOGGER = pino({
     name: '@reclaimprotocol/agent',
     timestamp: stdTimeFunctions.isoTime,
     base: { hostname: undefined, pid: undefined },
-});
+}, pino.destination(2));
 LOGGER.level = LOG_LEVEL;

package/lib/mcp/instructions.js

@@ -51,9 +51,9 @@ const TOPIC_SUMMARIES = {
     'auth': 'Signing in to the backend, and which token authorizes what.',
     'devtools-migration': 'Importing a public legacy provider with the same '
         + 'UUID.',
-    'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
-        + 'Docker, a remote Builder browser, or a custom CDP endpoint), '
-        + 'geolocation, live view, and launch troubleshooting.',
+    'browser': 'The default local browser, the opt-in modes (attach, the '
+        + 'Reclaim runtime in Docker, a remote Builder browser, a custom CDP '
+        + 'endpoint), geolocation, live view, and launch troubleshooting.',
     'capture': 'Tabs, sign-in detection, capturing through the navigation '
         + 'script, and picking an authenticated request to prove.',
     'draft': 'The OPRF/privacy decision, propose_provider, and the canonical '

package/lib/mcp/start.js

@@ -10,8 +10,9 @@ import { OLD_MODE_INSTRUCTIONS } from "../old/instructions.js";
 import { ReclaimSdkClient } from "../old/sdk-client.js";
 import { buildOldBackendTools } from "../old/tools/build.js";
 import { NAME, VERSION } from "../pkg.js";
+import { startZkFilesDownload } from "../proof/zk-files.js";
 import { registerTools } from "./api/tools.js";
-import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, releaseAllListeners, stopAllForwarders, } from "./tools/index.js";
+import { buildAgentState, buildAgentTools, buildBuilderAuthenticationTools, buildBuilderOrganizationTools, buildCredentialTools, buildLocalCredentialTools, buildModeTools, buildVerificationTools, disposeAgentState, readSession, releaseAllListeners, sessionRefreshingFetch, stopAllForwarders, } from "./tools/index.js";
 import { BUILDER_MODE_INSTRUCTIONS } from "./instructions.js";
 import { registerToolList } from "./server.js";
 export async function startMcpServer() {
@@ -31,11 +32,19 @@ export async function startMcpServer() {
     const agentToolsEnabled = !agentDisabled();
     /** The agent state this server registered, for shutdown to release. */
     let agentState;
+    const envToken = apiToken();
     const builderClient = new ReclaimClient({
         baseUrl: apiUrl(),
         // Builder access is orthogonal to publishing mode. A legacy-devtools
         // session can authenticate here solely to allocate a remote browser.
-        token: apiToken() || readSession()?.token,
+        token: envToken || readSession()?.token,
+        // The cached sign-in refreshes itself; an explicit RECLAIM_API_TOKEN
+        // takes precedence and is sent as is.
+        ...(envToken
+            ? {}
+            : {
+                fetch: sessionRefreshingFetch(oldMode ? 'authenticate_builder' : 'reclaim_authenticate'),
+            }),
         headers: { 'User-Agent': `${NAME}/${VERSION}` },
     });
     // Backend-mode toggle — available in both modes and regardless of whether
@@ -99,6 +108,12 @@ export async function startMcpServer() {
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Fetch the proof files in the background so the first proof doesn't wait
+    // for them. Progress goes to stderr; `check_attestor` reports the state,
+    // and every proof still awaits the same download.
+    if (agentToolsEnabled) {
+        startZkFilesDownload();
+    }
 }
 /** How long teardown gets before the process leaves anyway. */
 const SHUTDOWN_GRACE_MS = 10000;

package/lib/mcp/tools/agent/attach.d.ts

@@ -1,6 +1,7 @@
 import type { ReclaimClient } from '@reclaimprotocol/client/api';
 import { type CdpHandles, connectCdp, connectCdpUrl } from '../../../cdp/client.ts';
 import { dockerAvailable, startContainer } from '../../../cdp/container.ts';
+import { launchLocalBrowser, type LocalBrowser, waitForCdpReady } from '../../../cdp/launcher.ts';
 import type { ConfigStore } from '../../../config/store.ts';
 import { type RegisteredTool } from '../../server.ts';
 export type BrowserMode = 'dedicated' | 'attach' | 'builder' | 'custom' | 'container';
@@ -34,6 +35,8 @@ export interface AttachState {
     viewerPort?: number;
     /** Whether the runtime image had to be downloaded on this attach. */
     imagePulled?: boolean;
+    /** `dedicated` mode: the browser this attach launched, if it launched one. */
+    launched?: Omit<LocalBrowser, 'process'>;
     disposeRemote?: () => Promise<void>;
 }
 export interface AttachRef {
@@ -46,6 +49,9 @@ interface AttachDependencies {
     /** Injected so container mode is testable without Docker installed. */
     dockerAvailable: typeof dockerAvailable;
     startContainer: typeof startContainer;
+    /** Injected so the default launch is testable without a real browser. */
+    launchLocal: typeof launchLocalBrowser;
+    waitForCdp: typeof waitForCdpReady;
 }
 export declare function attachTool(state: AttachRef, builderClient?: ReclaimClient, beforeReplace?: () => Promise<void>, dependencies?: Partial<AttachDependencies>): RegisteredTool;
 export declare function disposeAttached(state: AttachRef): Promise<void>;

package/lib/mcp/tools/agent/attach.js

@@ -3,8 +3,7 @@ import assert from 'node:assert';
 import { connectCdp, connectCdpUrl, } from "../../../cdp/client.js";
 import { dockerAvailable, dockerMissingMessage, startContainer, } from "../../../cdp/container.js";
 import { suggestCountryFromIp } from "../../../cdp/geo.js";
-import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../../../cdp/launcher.js";
-import { defaultConfigPath } from "../../../config/store.js";
+import { defaultProfileDir, launchLocalBrowser, waitForCdpReady, } from "../../../cdp/launcher.js";
 import { defineTool } from "../../server.js";
 import { ensureLiveViewUrl } from "./live-view-url.js";
 /**
@@ -16,84 +15,13 @@ import { ensureLiveViewUrl } from "./live-view-url.js";
  * show — one on this machine is watched by looking at it.
  */
 export const SHAREABLE_MODES = new Set(['container']);
-/** Browser sources returned when the caller omits `mode`. Keep selection detail
- * here instead of repeating it in the always-loaded tool description. */
-const BROWSER_OPTIONS = [
-    {
-        mode: 'dedicated',
-        useCase: 'Working on your own machine',
-        label: 'Local Chrome, launched for you',
-        detail: 'Launches Chrome with a dedicated profile under '
-            + '~/.reclaim/chrome-profile. Nothing to set up, and the profile '
-            + 'persists, so a site you sign in to stays signed in. The easiest '
-            + 'choice when you are doing the work yourself.',
-        requires: [],
-        liveView: 'None, and none needed — the browser is on your screen.',
-    },
-    {
-        mode: 'attach',
-        useCase: 'Working on your own machine',
-        label: 'The Chrome you already have open',
-        detail: 'Connects to a Chrome you started yourself, keeping the tabs, '
-            + 'extensions and logins already in it. That Chrome must have been '
-            + 'started with BOTH --remote-debugging-port AND a non-default '
-            + '--user-data-dir: since Chrome 136 the debug flag is silently '
-            + 'ignored on the default profile.',
-        requires: ['port (default 9222)'],
-        liveView: 'None, and none needed — the browser is on your screen.',
-    },
-    {
-        mode: 'container',
-        useCase: 'Someone else has to sign in, or you need a phone',
-        label: 'Reclaim runtime in Docker — free, runs on your machine',
-        detail: 'Runs the Reclaim browser runtime (the same image the remote browser '
-            + 'uses) as a container on this machine, and gives you a link you can '
-            + 'send to whoever holds the account. They open it in any browser, '
-            + 'including a phone, and can see and click in it. Free — it is your '
-            + 'Docker and your bandwidth. Costs a 432 MB first-run download and '
-            + 'about 2 GB of RAM. The image is amd64, so Apple Silicon runs it '
-            + 'translated. OrbStack handles that itself; Docker Desktop needs '
-            + 'Rosetta enabled.',
-        requires: ['Docker running'],
-        liveView: 'Built in. This call returns a local `viewerUrl`, and '
-            + 'share_browser_view turns that into a public link for the person '
-            + 'helping you.',
-    },
-    {
-        mode: 'builder',
-        useCase: 'Someone else has to sign in, or you need a phone',
-        label: 'Remote browser, hosted by Reclaim — CHARGEABLE',
-        detail: 'A browser allocated in Reclaim\'s cloud, billed against the '
-            + 'organization\'s quota. Nothing to install, and the shareable link '
-            + 'comes back immediately. It is also the only way to browse a site '
-            + 'from a SPECIFIC COUNTRY — its whole egress is routed there. '
-            + 'Geolocation is optional: omit countryCode to be offered a '
-            + 'suggestion, or pass skipCountry to allocate without geo-routing.',
-        requires: [
-            'Builder authentication',
-            'orgId (auto-resolved when you have only one)',
-            'quota — this one costs money',
-        ],
-        liveView: 'Included. This call returns a hosted liveViewUrl to pass on; '
-            + 'share_browser_view does not apply.',
-    },
-    {
-        mode: 'custom',
-        useCase: 'Advanced',
-        label: 'A CDP endpoint you supply',
-        detail: 'Connects to any ws:// or wss:// CDP websocket — a browser you run '
-            + 'elsewhere, or another tool\'s. The URL is treated as a credential: '
-            + 'never logged, persisted, or returned. Only pick this if you were '
-            + 'given an endpoint and know why.',
-        requires: ['cdpUrl'],
-        liveView: 'None, unless you pass your own liveViewUrl alongside the cdpUrl.',
-    },
-];
 const DEFAULT_DEPENDENCIES = {
     connectLocal: connectCdp,
     connectRemote: connectCdpUrl,
     dockerAvailable,
     startContainer,
+    launchLocal: launchLocalBrowser,
+    waitForCdp: waitForCdpReady,
 };
 export function attachTool(state, builderClient, beforeReplace, 
 // Partial so a caller can stub one thing without restating the rest — the
@@ -104,16 +32,15 @@ dependencies = {}) {
     };
     return defineTool({
         name: 'attach_browser',
-        description: 'Connects the authoring tools to a browser that loads the '
-            + 'developer\'s sign-in page and target site. `builder` and '
-            + '`container` run the browser remotely or in Docker, away from the '
-            + 'developer\'s own profile; `dedicated`, `attach`, and `custom` use a '
-            + 'local or supplied Chrome. Call without `mode` to receive the '
-            + 'options, ask the developer to choose, then call again once with '
-            + 'the chosen mode. `builder` consumes quota. Only `container` and '
-            + '`builder` support a shareable live view. Relay returned live-view '
-            + 'URLs verbatim. See how_it_works({ topic: "browser" }) for '
-            + 'selection, geolocation, and lifecycle.',
+        description: 'Opens a visible browser on the developer\'s own machine for '
+            + 'sign-in and capture. Call it with no arguments and do not ask '
+            + 'which browser to use: it launches installed Chrome (else '
+            + 'Chromium, Edge, or a one-time Chrome for Testing download) with '
+            + 'the persistent Reclaim profile. Pass `mode` only when the '
+            + 'developer explicitly asks for that mode: `attach` (their running '
+            + 'Chrome on `port`), `container` (Docker), `custom` (`cdpUrl`), or '
+            + '`builder` (billed). Never offer or pick those yourself. See '
+            + 'how_it_works({ topic: "browser" }).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -122,6 +49,8 @@ dependencies = {}) {
                     enum: [
                         'dedicated', 'attach', 'container', 'builder', 'custom',
                     ],
+                    description: 'Omit for the default local browser (`dedicated`). Set '
+                        + 'only to a mode the developer explicitly asked for.',
                 },
                 attachMode: {
                     type: 'string',
@@ -159,31 +88,12 @@ dependencies = {}) {
         annotations: { openWorldHint: true, destructiveHint: false },
     }, async (parsed) => {
         const persisted = state.config.read()?.browser_agent;
-        // Deliberately NOT falling back to the persisted mode: which browser
-        // to drive is the developer's call every time (a remote one costs
-        // quota, a local one exposes their own profile), and silently reusing
-        // last session's answer takes that decision away from them. The
-        // persisted choice is offered back as a default to suggest, not
-        // applied.
-        const mode = parsed.mode ?? parsed.attachMode;
-        if (!mode) {
-            return {
-                needsChoice: true,
-                message: 'Ask FIRST whether they will be doing this themselves or '
-                    + 'someone else has to sign in — that answer decides half the '
-                    + 'list. Themselves: `dedicated` or `attach`. Someone else, or '
-                    + 'a phone-only site: `container` (free, needs Docker) or '
-                    + '`builder` (no install, chargeable) — the only two that give '
-                    + 'you a link to send. Then present the matching options and '
-                    + 'call attach_browser again with the `mode` they pick. Do not '
-                    + 'pick one for them.',
-                options: BROWSER_OPTIONS,
-                ...(persisted?.attachMode
-                    ? { previouslyUsed: persisted.attachMode }
-                    : {}),
-                configPath: defaultConfigPath(),
-            };
-        }
+        // The default is a visible browser on the developer's own machine,
+        // with no question first. Every other mode costs something (Docker,
+        // quota, the developer's own profile) and is used only when the
+        // developer asked for it by name, so a persisted choice is never
+        // reapplied either.
+        const mode = parsed.mode ?? parsed.attachMode ?? 'dedicated';
         let orgId = parsed.orgId;
         if (mode === 'builder' && !orgId) {
             assert(builderClient, badRequest('Builder browser service is unavailable'));
@@ -279,7 +189,17 @@ dependencies = {}) {
             ...(next.countryCode ? { countryCode: next.countryCode } : {}),
             ...(next.containerName ? { containerName: next.containerName } : {}),
             ...(canShare ? { liveViewAvailable: true } : {}),
+            ...(next.launched ? { browser: next.launched.source } : {}),
             _notes: [
+                ...(next.launched?.source === 'chrome-for-testing'
+                    ? ['Launched Chrome for Testing'
+                            + (next.launched.downloaded
+                                ? ', downloaded just now into ~/.reclaim/browsers (later '
+                                    + 'launches reuse it)'
+                                : ' from ~/.reclaim/browsers')
+                            + `, because: ${next.launched.fallbackReason}. Mention `
+                            + 'this to the developer in one line.']
+                    : []),
                 ...(next.imagePulled
                     ? ['The browser runtime image was downloaded just now (about '
                             + '432 MB, about 1.3 GB on disk). Mention it — later attaches '
@@ -303,9 +223,12 @@ dependencies = {}) {
                     : []),
                 ...(!localView && !hostedView
                     ? ['This browser has no live view: it runs on the developer\'s '
-                            + 'own machine, so they watch it by looking at it. If someone '
-                            + 'ELSE needs to see or drive it, say that `container` mode '
-                            + 'runs a browser with a shareable live view built in.']
+                            + 'own machine, so they watch it by looking at it. Do not '
+                            + 'offer other modes. Tell the developer once, as a side '
+                            + 'note, that if a volunteer is helping them sign in, a '
+                            + 'shareable link can be set up (`container` mode and '
+                            + 'share_browser_view); do not ask or set it up unless they '
+                            + 'ask.']
                     : []),
             ],
         };
@@ -398,24 +321,41 @@ async function connect(mode, parsed, persisted, builderClient, dependencies) {
         }
     }
     const port = parsed.port ?? persisted?.port ?? 9222;
+    let launched;
     if (mode === 'dedicated') {
         try {
-            await waitForCdpReady(port, 500);
+            // Reuse the browser an earlier attach launched on this port.
+            await dependencies.waitForCdp(port, 500);
         }
         catch {
-            launchChrome({ port, profileDir: defaultProfileDir() });
-            await waitForCdpReady(port, 10000);
+            const browser = await dependencies
+                .launchLocal({ port, profileDir: defaultProfileDir() });
+            // The browser outlives this attach on purpose, so its process handle
+            // is not kept.
+            launched = {
+                binary: browser.binary,
+                source: browser.source,
+                downloaded: browser.downloaded,
+                ...(browser.fallbackReason
+                    ? { fallbackReason: browser.fallbackReason }
+                    : {}),
+            };
         }
     }
     else {
-        await waitForCdpReady(port, 2000).catch(() => {
+        await dependencies.waitForCdp(port, 2000).catch(() => {
             throw new Error(`attach mode: nothing answering CDP on port ${port}. Chrome must `
                 + `be launched with --remote-debugging-port=${port} AND `
                 + '--user-data-dir=<some-non-default-path>. Chrome 136+ ignores '
                 + 'the debugging flag for the default profile.');
         });
     }
-    return { handles: await dependencies.connectLocal(port), mode, port };
+    return {
+        handles: await dependencies.connectLocal(port),
+        mode,
+        port,
+        ...(launched ? { launched } : {}),
+    };
 }
 async function disposeState(state) {
     try {