barebrowse 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,232 @@
 # Changelog
 
+## 0.9.0
+
+Phase B — every H1–H9 from `docs/02-features/fix-plan.md` shipped one
+commit each, plus the post-Phase-B code-review fixes. Two new modules
+of functionality (iframe pipeline, download capture), two new public
+API methods (`reload`, `onDialog`), six new MCP tools, opt-in `eval`,
+per-tool MCP timeouts, full stealth coverage, and a tightened bot-
+detection heuristic. 23 new regression tests. 123/123 tests pass.
+
+See `docs/02-features/fix-plan.md` (Phase B section) and the per-fix
+entries in `docs/03-logs/bug-log.md`. Headlines:
+
+### Iframe / OOPIF support (H2)
+- `Accessibility.getFullAXTree` stops at frame boundaries; pre-H2,
+  Stripe, reCAPTCHA, embedded login forms, and most ads were invisible.
+- `createPage()` now wires `Target.setAutoAttach({autoAttach: true,
+  flatten: true})` and listens for `Target.attachedToTarget` to register
+  every iframe's CDP session in a `framesByFrameId` map (recursive).
+- `ariaTree()` walks `Page.getFrameTree`, fetches each frame's AX tree
+  on the right session (child for OOPIF, main with `frameId` param for
+  same-origin), splices children under iframe placeholders identified
+  via `DOM.getFrameOwner`.
+- Refs are globally unique via a flat counter shared across frames;
+  refMap stores `{session, backendNodeId}` so `click`/`type`/`hover`/
+  `select`/`upload` route to the correct CDP session. Visible
+  `[ref=N]` format unchanged.
+- `--site-per-process` added to launch flags so every iframe (including
+  same-origin) becomes OOPIF with a dedicated session — required
+  because `DOM.getBoxModel` returns frame-local coords while
+  `Input.dispatchMouseEvent` on the parent session uses parent-viewport
+  coords; OOPIF gives each frame its own Input domain.
+- `drag()` between elements in different frames now errors rather than
+  mixing sessions.
+
+### Attach to a running browser (H1)
+- `connect({port: 9222})` attaches to a Chromium the user already
+  started (`chromium --remote-debugging-port=9222`). New
+  `attach({port})` helper in `chromium.js` returns a browser handle
+  with `process: null, ownedProfileDir: null` so `cleanupBrowser` is
+  a no-op — we never kill or clean up a browser we didn't start.
+- Attach mode skips stealth (would persist via
+  `addScriptToEvaluateOnNewDocument`), `Browser.setPermission`
+  (browser-wide — would leak deny-states), download capture (don't
+  override the user's preference), and the two hybrid-fallback rewind
+  branches in `goto()` (we don't own the browser).
+- `close()` still closes the tab we created; the browser keeps running.
+
+### Downloads (H7)
+- `Browser.setDownloadBehavior({behavior: 'allowAndName',
+  downloadPath, eventsEnabled: true})` wired in `connect()`. Falls
+  back to `'allow'` on older Chrome; silent if neither works (downloads
+  still happen, just unobserved).
+- Per-session `mkdtemp('/tmp/barebrowse-dl-*')` cleaned up on `close()`;
+  caller-supplied `opts.downloadPath` left alone.
+- Live `page.downloads` array of `{guid, url, suggestedFilename,
+  savedPath, state, totalBytes, receivedBytes}`. Listeners registered
+  BEFORE `setDownloadBehavior` is sent (event ordering).
+- Skipped entirely in attach mode.
+
+### Stealth completeness (H4)
+- `Network.setUserAgentOverride` strips "HeadlessChrome" from the UA in
+  HTTP request headers AND `navigator.userAgent`. UA read from
+  `Browser.getVersion` so version/platform fields stay accurate across
+  Chromium releases.
+- New JS patches: `WebGLRenderingContext`/`WebGL2` `getParameter`
+  spoofs `UNMASKED_VENDOR_WEBGL` / `UNMASKED_RENDERER_WEBGL` to
+  Intel pair (the single most-used headless fingerprint);
+  `navigator.hardwareConcurrency` = 8; `navigator.deviceMemory` = 8;
+  full `chrome.runtime` enum shape (PlatformOs, OnInstalledReason,
+  etc.); `Notification` constructor + `permission: 'default'`;
+  `Permissions.query('notifications')` mirrors `Notification.permission`
+  instead of returning hardcoded `'prompt'`.
+
+### Bot-detection heuristic tightened (H9)
+- Pre-H9 `nodeCount < 50` alone flagged any minimal legitimate page;
+  generic phrases `access denied`/`unknown error`/`permission denied`
+  flagged real HTTP 4xx/5xx pages, kicking hybrid into a costly
+  headed launch for nothing.
+- Split into STRONG_PHRASES (Cloudflare's "Just a moment", "Attention
+  Required", "verify you are human" etc. — fire alone regardless of
+  size) and WEAK_PHRASES (generic phrases — only fire when ALSO
+  tiny: `nodeCount < 30` or `text.length < 50`). Pure low-node-count
+  without a phrase no longer flags. `isChallengePage` exported so
+  tests can pin the contract.
+
+### New connect() methods
+- **H3** `page.reload({ignoreCache, timeout})` — `Page.reload` wrapper
+  with same SPA-fallback semantics as `goBack`/`goForward`. Clears
+  `refMap` so pre-reload refs reject.
+- **H8** `page.onDialog(handler)` — handler receives
+  `{type, message, defaultPrompt}` and may return `{accept, promptText}`
+  to override the default auto-accept. Pass `null` to restore.
+  Persistent across hybrid fallback / `switchTab` / `createTab` —
+  every `setupDialogHandler` reads the same closure.
+- **H7** `page.downloads` — live array (see above).
+
+### MCP server (H5 + H6)
+- **H5:** new `TIMEOUTS` table replacing the blanket 30s — `goto`/
+  `reload`/`wait_for` 60s; `back`/`forward` 30s; `click`/`type`/
+  `press`/`scroll`/`hover`/`select`/`drag`/`snapshot`/`eval` 15s;
+  `tabs` 5s; `pdf`/`screenshot`/`upload` 45s.
+- **H6:** six new tools — `reload`, `screenshot`, `wait_for`, `tabs`
+  (with optional `switchTo: N`), `select`, `hover`. All wired through
+  the right `TIMEOUTS[name]`; mutating tools use `{retry: false}`.
+- **H6 opt-in:** `eval` tool registered only when
+  `BAREBROWSE_MCP_EVAL=1` is set. `Runtime.evaluate` in an
+  authenticated session is the load-bearing risk (cookies/localStorage
+  exfiltration). CLI/connect()/daemon keep `eval`; MCP gates it.
+- `TIMEOUTS` and `TOOLS` exported; `runStdio()` exported so `cli.js`
+  can launch the JSON-RPC loop explicitly (the earlier auto-start
+  isMain guard broke `npx barebrowse mcp` — caught in code review).
+- `serverInfo.version` now reads from `package.json` (was hardcoded
+  '0.7.1' — drift caught in same review).
+
+### CLI / daemon parity
+- `barebrowse reload [--no-cache]` and `barebrowse downloads`
+  subcommands added.
+- `--download-path=DIR` flag plumbs through `startDaemon` →
+  `runDaemonInternal` → `connect()`.
+
+### bareagent adapter
+- Three new tools: `reload`, `wait_for`, `downloads`. `onDialog`
+  intentionally stays connect()-only (callback shape doesn't fit
+  tool loop).
+
+### MCP config diagnostics (post-Phase-B follow-up)
+- **`barebrowse doctor`** scans every known MCP config location
+  (Claude Code user/project/local, Claude Desktop, Cursor, VS Code)
+  for `barebrowse` entries. Prints CONFLICT + both endpoint paths
+  when scopes diverge. Closes the "Conflicting scopes" warning
+  Claude Code surfaces but barebrowse itself was silent about.
+- **`barebrowse install`** detects existing entries with a different
+  endpoint and refuses to overwrite without `--force` — was
+  silently clobbering, which is how scope conflicts accumulated in
+  the first place.
+- **`barebrowse mcp`** writes a one-line stderr banner at startup
+  (`barebrowse mcp v<X.Y.Z> | serving from <abs path> | pid <N>`)
+  so a stuck agent is diagnosable from the MCP log.
+
+### Test infrastructure
+- **`cleanupBrowser` profile-dir rm hardened** to 25×100ms±jitter
+  (was 10×100ms). `--site-per-process` from H2 spawns a renderer
+  per iframe; under parallel test load the old 1s window wasn't
+  always enough to absorb post-exit file flushing.
+
+### Tests
+- 27 new regression tests across `connect.test.js` (H1, H2, H3, H7,
+  H8), `stealth.test.js` (H4 — new file), `mcp.test.js` (H5 timeouts,
+  H6 tool surface + eval env-var gating, npx cli.js mcp regression),
+  `challenge.test.js` (H9 — new file, 9 cases), `cli.test.js`
+  (reload + downloads subcommands, plus the four MCP-config-
+  diagnostics tests for doctor + install --force + mcp banner).
+  Total: 127 (54 unit + 73 integration).
+
+## 0.8.0
+
+Stability release — 11 fixes from the QA review of 2026-05-17. Adds a
+new module (`network-idle.js`), introduces `cleanupBrowser()` helper,
+and forwards `binary`/`userDataDir` opts through `connect()`/`browse()`.
+17 new regression tests. 97/97 tests pass.
+
+See `docs/02-features/fix-plan.md` for the full scope and the per-fix
+entries in `docs/03-logs/bug-log.md`. Headlines:
+
+### Lifecycle & cleanup
+- **F2/F3:** Temp profile dirs no longer leak. New `cleanupBrowser()` helper
+  awaits process exit, retries `rmSync` on ENOTEMPTY/EBUSY. On parent
+  crash, module-level `process.on('exit'|'SIGINT'|'SIGTERM'|'SIGHUP')`
+  handlers SIGKILL all tracked browsers and reap their dirs.
+- **F1:** `page.cdp` escape hatch is now a getter — survives hybrid
+  fallback / `switchTab` swapping the underlying session. Previously
+  `daemon.js` console + network listeners silently died after any
+  fallback.
+
+### Correctness fixes
+- **F4:** `switchTab(idx)` now actually swaps the working CDP session
+  (re-attaches and rebinds the closure). Was only foregrounding the tab.
+- **F5:** `goto()` invalidates `refMap` so stale refs from the prior page
+  error clearly instead of resolving wrong-element clicks.
+- **F8:** `goBack()`/`goForward()` await `Page.loadEventFired` instead of
+  a fixed 500ms sleep — snapshots taken immediately after now reliably
+  reflect the new page. Also invalidate `refMap`.
+- **F9:** `waitForNetworkIdle` extracted to `src/network-idle.js`; uses a
+  Set of requestIds so orphan finish events can't drive the tracker
+  negative and resolve early.
+
+### MCP server
+- **F6:** `withRetry({ retry: false })` for state-mutating tools
+  (`click`/`type`/`press`/`scroll`/`back`/`forward`/`drag`/`upload`).
+  Idempotent tools (`goto`/`snapshot`/`pdf`) keep the retry default.
+  Mutating ops no longer double-submit on a fresh blank page after a
+  partial first attempt.
+- `browse`/`goto` tool descriptions reworded to position `browse` as the
+  headless fallback (not a competitor to WebFetch) and `goto` as the
+  explicit interactive-session entrypoint.
+
+### Tab handling
+- **F7:** `createTab()` wires the dialog handler on the new tab's
+  session — JS dialogs in sub-tabs no longer hang navigation forever.
+
+### API
+- **L2:** `connect()`/`browse()` now honor `binary` and `userDataDir`
+  opts (forwarded through all `launch()` calls including hybrid
+  fallback). `port` opt for attach-to-running-browser is queued for the
+  next release (H1 in `fix-plan.md`).
+- **L1:** Dropped dead `strictPatterns` block in `consent.js`.
+
+### Tests
+- 17 new regression tests across `cdp.test.js`, `mcp.test.js`,
+  `network-idle.test.js`, `connect.test.js` + a subprocess fixture
+  (`test/fixtures/launch-and-wait.mjs`). Total: 97 (44 unit + 53
+  integration).
+
+## 0.7.1
+
+Fix: timeout now triggers auto-retry instead of bypassing it.
+
+### Bug fix (`mcp-server.js`)
+- **Root cause:** The 30s timeout was a `Promise.race` *outside* `withRetry()`. When a page timed out, the race rejected immediately — `withRetry` never got a chance to reset the session and retry. Timeouts also didn't match `isCdpDead()`, so even if they did reach `withRetry`, they wouldn't be retried.
+- **Fix:** Moved per-attempt timeout *inside* `withRetry()`. Each attempt gets its own 30s deadline. On timeout or CDP death, the session resets and a fresh attempt runs. The outer `Promise.race` is removed entirely.
+- `isCdpDead()` renamed to `isTransient()` — now also matches timeout errors (`"Timeout waiting for CDP event"`, `"timed out"`)
+- Non-transient errors (validation, unknown tool) are still not retried
+
+### Tests
+- 11 new unit tests in `test/unit/mcp.test.js`: `isTransient` detection (CDP death, timeouts, non-transient), `withRetry` behavior (success, CDP retry, timeout retry, no-retry for validation, double-failure, no-timeout mode)
+- 80 total tests (39 unit + 41 integration)
+
 ## 0.7.0
 
 MCP resilience: timeouts, auto-retry, LLM-friendly scroll, and click fallback for hidden elements.

package/LICENSE

@@ -1,21 +1,202 @@
-MIT License
-
-Copyright (c) 2026 hamr0
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,8 @@
+barebrowse
+Copyright 2026 hamr0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -9,6 +9,11 @@
   barebrowse
 ```
 
+<p align="center">
+  <img src="https://img.shields.io/github/package-json/v/hamr0/barebrowse?label=version&color=2a4f8c" alt="version (auto from package.json)">
+  <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
+</p>
+
 > Your agent browses like you do -- same browser, same logins, same cookies.
 > Prunes pages down to what matters. 40-90% fewer tokens, zero wasted context.
 
@@ -87,7 +92,9 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
 }
 ```
 
-12 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `back`, `forward`, `drag`, `upload`, `pdf`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Session runs in hybrid mode with automatic cookie injection. All tools have timeouts (30s/60s) and auto-retry on transient failures.
+18 tools: `browse`, `goto`, `snapshot`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`. Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
+
+Troubleshooting MCP setup: `npx barebrowse doctor` scans every known config location and flags scope conflicts. `npx barebrowse install --force` overwrites an existing entry pointing at a different endpoint.
 
 ### 3. Library -- for agentic automation
 
@@ -103,6 +110,24 @@ For code examples, API reference, and wiring instructions, see **[barebrowse.con
 | **Headed** | Auto-launches a visible Chromium window | Bot-detected sites, visual debugging, CAPTCHAs |
 | **Hybrid** | Tries headless first, auto-launches headed if blocked | General-purpose agent browsing |
 
+### Attach to your already-running browser
+
+Start Chromium yourself with a debug port, then drive your real logged-in session:
+
+```bash
+chromium --remote-debugging-port=9222
+```
+
+```js
+import { connect } from 'barebrowse';
+const page = await connect({ port: 9222 });
+await page.goto('https://your-logged-in-app.example.com');
+const snap = await page.snapshot();
+await page.close(); // closes only the tab barebrowse opened — your browser keeps running
+```
+
+No clone profile, no fresh cookies — the agent sees what you see.
+
 ## What it handles automatically
 
 Cookie consent walls (29 languages, with real mouse click fallback for stubborn CMPs), login walls (cookie extraction from your browsers), bot detection (ARIA node count heuristic + stealth patches + automatic headed fallback — snapshot shows `[BOT CHALLENGE DETECTED]` warning when blocked), permission prompts, SPA navigation, JS dialogs, off-screen elements, pre-filled inputs, ARIA noise, and profile locking. The agent doesn't think about any of it.
@@ -185,15 +210,17 @@ URL -> find/launch browser (chromium.js)
 
 ## The bare ecosystem
 
-Three vanilla JS modules. Zero dependencies. Same API patterns.
+Four vanilla JS modules. Zero deps where possible (bareguard has one). Same API patterns.
+
+| | [**bareagent**](https://npmjs.com/package/bare-agent) | [**barebrowse**](https://npmjs.com/package/barebrowse) | [**baremobile**](https://npmjs.com/package/baremobile) | [**bareguard**](https://npmjs.com/package/bareguard) |
+|---|---|---|---|---|
+| **Does** | Gives agents a think→act loop | Gives agents a real browser | Gives agents an Android device | Gates everything an agent does |
+| **How** | Goal in → coordinated actions out | URL in → pruned snapshot out | Screen in → pruned snapshot out | Action in → allow / deny / human-asked out |
+| **Replaces** | LangChain, CrewAI, AutoGen | Playwright, Selenium, Puppeteer | Appium, Espresso, UIAutomator2 | Hand-rolled allowlists, scattered policy code |
+| **Interfaces** | Library · CLI · subprocess | Library · CLI · MCP | Library · CLI · MCP | Library |
+| **Solo or together** | Orchestrates the others as tools | Works standalone | Works standalone | Embedded in bareagent's loop; usable by any runner |
 
-| | [**bareagent**](https://npmjs.com/package/bare-agent) | [**barebrowse**](https://npmjs.com/package/barebrowse) | [**baremobile**](https://npmjs.com/package/baremobile) |
-|---|---|---|---|
-| **Does** | Gives agents a think→act loop | Gives agents a real browser | Gives agents an Android device |
-| **How** | Goal in → coordinated actions out | URL in → pruned snapshot out | Screen in → pruned snapshot out |
-| **Replaces** | LangChain, CrewAI, AutoGen | Playwright, Selenium, Puppeteer | Appium, Espresso, UIAutomator2 |
-| **Interfaces** | Library · CLI · subprocess | Library · CLI · MCP | Library · CLI · MCP |
-| **Solo or together** | Orchestrates both as tools | Works standalone | Works standalone |
+> **Reach 50+ messengers with one Docker container via [beeperbox](https://github.com/hamr0/beeperbox)** — a headless Beeper Desktop that exposes WhatsApp, iMessage, Signal, Telegram, Slack, Discord, RCS, SMS and more as a single MCP server. Wire it through bareagent's MCP bridge; bareguard policies the invocations like any other tool (per-chat allowlists, ask patterns on destructive sends, all the usual layered defense).
 
 **What you can build:**
 
@@ -207,4 +234,4 @@ Three vanilla JS modules. Zero dependencies. Same API patterns.
 
 ## License
 
-MIT
+Apache-2.0 — see [LICENSE](LICENSE).