bwb-browser 3.2.0 → 4.0.1

package/AGENTS.md

@@ -1,12 +1,12 @@
 # bwb-browser — Agent Integration Guide
 
 > **Author:** Krish Tiwari ([@krshforever](https://github.com/krshforever))
-> **Package:** [`bwb-browser`](https://www.npmjs.com/package/bwb-browser) · 76KB source · 26 tools
+> **Package:** [`bwb-browser`](https://www.npmjs.com/package/bwb-browser) · ~136KB source · 26 tools · static-first (v4)
 > **Last updated:** 2026-08-06
 
 ## What is bwb?
 
-**Browser Without Bloat** — a lightweight MCP server that gives any AI agent browser superpowers. 76KB. 26 tools. Zero heavy dependencies.
+**Browser Without Bloat** — a lightweight MCP server that gives any AI agent browser superpowers. ~136KB source. 26 tools. Static-first: plain pages never spawn Chromium. Zero native dependencies.
 
 While other MCP browser tools ship a full browser binary (Playwright MCP = ~250MB, Puppeteer MCP = ~400MB), bwb uses **raw Chrome DevTools Protocol (CDP)** — the protocol Chrome speaks natively. It auto-detects the browser already on your system.
 
@@ -64,9 +64,9 @@ bwb --version
 Give this to any AI agent (Claude, OpenCode, Gemini, etc.) to auto-install and configure bwb:
 
 ```
-I want you to install and use bwb-browser — a 76KB MCP browser automation server with 26 tools.
+I want you to install and use bwb-browser — a lightweight MCP browser automation server with 26 tools.
 
-bwb is Browser Without Bloat. It uses raw Chrome DevTools Protocol (no Playwright, no Puppeteer).
+bwb is Browser Without Bloat. Static-first: plain pages are fetched + extracted with zero Chromium; JS pages escalate automatically. It uses raw Chrome DevTools Protocol (no Playwright, no Puppeteer) only when rendering is actually needed.
 It has 26 tools including:
 
 - `browser_act` — natural language interaction ("search for X", "click the button", "what's on this page")
@@ -116,20 +116,22 @@ Created by Krish Tiwari (@krshforever) from a phone on a train in India. npm: bw
 
 5. Verify the config is valid JSON and the file has proper syntax.
 
-6. Test the integration by calling `browser_status` tool — it should return `connected: true` 
-   (it starts Chromium automatically on first call).
+6. Test the integration by calling `browser_status` tool — it should return `connected: true`
+   (static-first: plain pages never start Chromium; JS pages start it on first CDP call).
 
 ## Skill: I Know How to Use bwb
 
 When using bwb for web tasks, follow these patterns:
 
 ### Basic Browsing
-- `browser_goto({url: "https://example.com"})` — navigate to a page
-- `browser_title()` — check page title
-- `browser_screenshot({selector: "#chart"})` — take a screenshot (whole page, viewport, or one element; saves to /storage/emulated/0/Download/bwb-screenshots/ on Android or ~/bwb-screenshots/ on desktop)
+- `browser_goto({url: "https://example.com"})` — navigate (static-first: `mode: "static"` needs no browser; `mode: "browser"` escalated to CDP)
 - `browser_text()` — get page text content
+- `browser_screenshot({selector: "#chart"})` — take a screenshot (whole page, viewport, or one element; saves to /storage/emulated/0/Download/bwb-screenshots/ on Android or ~/bwb-screenshots/ on desktop)
 - `browser_html()` — get page HTML
 - `browser_elements({kind: "links"|"buttons"|"inputs"|"headings"})` — find interactive elements
+- `browser_status()` — page title/URL live in `targets`, plus resource readings and active profile
+
+Every tool response ends with a `[bwb resources]` footer (MCP + Chromium MB, tabs, ok/watch/critical). On critical, bwb sheds load itself and says so — read the footer before spawning more work.
 
 ### Interaction
 - `browser_fill({selector: "#search", text: "query"})` — fill input fields
@@ -173,8 +175,8 @@ internally — not just what it looks like.
 | `browser_click` | Click an element (native CDP mouse events) |
 | `browser_fill` | Fill an input field (native CDP keyboard events) |
 | `browser_elements` | List interactive elements by kind |
-| `browser_title` | Get page title |
-| `browser_url` | Get current URL |
+| `browser_download` | Download media (needs system yt-dlp, consent-gated) |
+| `browser_export` | Export md/txt/html (pdf/docx/pptx need pip libs, consent-gated) |
 | `browser_back` | Go back in history |
 | `browser_eval` | Execute JavaScript (with exception capture) |
 | `browser_setViewport` | Change viewport size |
@@ -224,6 +226,18 @@ BWB_CHROME_PATH=/path/to/chrome bwb
 bwb --browser-path /path/to/chrome
 ```
 
+### Attach Mode (drive the window you're looking at)
+```bash
+# Launch your browser with remote debugging first, e.g.:
+#   brave --remote-debugging-port=9222
+BWB_ATTACH_PORT=9222 bwb
+# or
+bwb --attach-port 9222
+```
+Guest mode: no spawn, no kill, no journal restore. `browser_newTab` opens a
+VISIBLE tab in your window. Auto-shed is disabled (those are your real tabs) —
+pressure is reported, you close them. `browser_status` shows `attached: true`.
+
 ---
 
 ## License

package/README.md

@@ -1,8 +1,21 @@
 # bwb-browser
 
-**Browser Without Bloat** — 76KB. 26 tools. Zero dependencies. Runs on your phone.
+**Browser Without Bloat** — 136KB source. 26 tools. Static-first. Runs on your phone, survives it too.
 
-A lightweight MCP server that gives any AI agent browser superpowers. Written by a guy in India on Termux because the existing tools were 200MB of "why."
+A lightweight MCP server that gives any AI agent browser superpowers. Written by a guy in India on Termux because the existing tools were 200MB of "why" — then rewritten when Android kept killing those tools mid-run.
+
+---
+
+## v4: The Browser Starts Only When It Must
+
+v1–v3 made the server light but spawned Chromium for everything — including reading a README. Android's out-of-memory killer ate whole Termux sessions for that. v4 inverts the default:
+
+- **Static-first fetch ladder** — plain pages are fetched + extracted with zero Chromium. `browser_goto` returns `mode: "static"` in milliseconds. JS pages escalate to CDP automatically (`mode: "browser"` + reason). Dead URLs error without spawning anything.
+- **Vigilance system** — every tool response carries a `[bwb resources]` footer. On critical pressure bwb hibernates tabs itself, tears down at one tab, journals everything, and tells the agent what it did.
+- **Survival profile** — `--lean` auto-enables on Termux (capped renderers, 3-tab cap, 5-minute mayfly teardown, 256MB JS heap). Runs on a 1GB VPS. Your tabs resurrect from the journal after any kill.
+- **On-demand capabilities** — `browser_download` / `browser_export` ship as verbs, not weight. Missing backends (yt-dlp, reportlab) prompt for consent install. Nothing heavy is ever bundled.
+
+Measured on-device: a single YouTube tab costs **746MB** of Chromium tree. That's why the ladder exists.
 
 ---
 
@@ -12,17 +25,20 @@ Every other MCP browser tool ships a full browser binary. Playwright MCP? ~250MB
 
 bwb uses **raw Chrome DevTools Protocol (CDP)** — the same protocol Chrome speaks natively. It auto-detects the browser already on your system. No downloads. No binary mismatches. No "why is my disk full" panic.
 
-| Factor | bwb | Playwright MCP | Puppeteer MCP |
+| Factor | bwb v4 | Playwright MCP | Puppeteer MCP |
 |--------|-----|----------------|---------------|
-| Source size | **76KB** | ~50MB+ | ~100MB+ |
-| Total install | **~1MB** | ~250MB | ~400MB |
+| Source size | **~136KB** | ~50MB+ | ~100MB+ |
+| Published tarball | **38.8 kB** | — | — |
+| Total install (npm) | **~62MB, zero browsers** | ~250MB | ~400MB |
 | Bundled browser | **None** | Chromium (~200MB) | Chromium (~300MB) |
+| Chromium spawns for plain pages | **Never (static-first)** | Always | Always |
 | Works on Termux/Android | **✅ Yes** | ❌ | ❌ |
-| Zero deps (no node_modules hell) | **✅ Yes** | ❌ | ❌ |
+| Survives 1GB RAM / phone OOM | **✅ Lean profile + vigilance** | ❌ | ❌ |
+| Zero native deps | **✅ Yes** | ❌ | ❌ |
 | Live event streaming | **✅** | ❌ | ❌ |
 | Natural language interaction | **✅** | ❌ | ❌ |
 | Persistent sessions | **✅** | ❌ | ❌ |
-| CPU profile at idle | Basically nothing | 🐌 | 🐌 |
+| CPU profile at idle | Mayfly teardown (Termux) | 🐌 | 🐌 |
 
 ---
 
@@ -74,7 +90,7 @@ Create tabs, close them, switch between them, save cookies, load them back. Like
 
 Normalizes `navigator.webdriver`, plugins, languages, and user-agent for testing environments. Not "stealth mode" — just honest fingerprint normalization so your tests actually match real user conditions.
 
-### 7. Element Screenshots (new in 3.2.0)
+### 7. Element Screenshots
 
 Capture just one element — a login form, a chart, a product card — not the whole page:
 
@@ -89,20 +105,24 @@ Every screenshot is saved to disk (Android: `/storage/emulated/0/Download/bwb-sc
 
 ---
 
-## What's New in 3.2.0
+## What's New in 4.0.0 — "Lightweight Like Air"
+
+### Static-first fetch ladder
+- **`browser_goto` no longer spawns Chromium for plain pages** — fetch + extract in milliseconds (`mode: "static"`). JS pages escalate automatically (`mode: "browser"` + reason). Dead URLs error without spawning anything.
+- **On-demand capabilities** — `browser_download` / `browser_export` ship as verbs, not weight. Missing backends prompt for consent install. Nothing heavy is ever bundled.
+
+### Vigilance system
+- **Every tool response carries a `[bwb resources]` footer** — MCP + Chromium MB, tabs, ok/watch/critical. `browser_watch` streams memory samples on its existing poll rhythm.
+- **Thresholds act, then report** — critical pressure hibernates tabs, tears down at one tab, journals everything. The agent reads about the save, never discovers the OOM.
 
-### New
-- **`browser_screenshot({ selector })`** — element-level capture. Grab just the login form, the chart, the product card — not the whole page.
-- **Screenshot directory auto-detect** — Termux/Android → `/storage/emulated/0/Download/bwb-screenshots/`, desktop → `~/bwb-screenshots/`. Override with `BWB_SCREENSHOTS_DIR`.
+### Survival profile
+- **`--lean` auto-enables on Termux** — capped renderers, silenced background services, 3-tab cap, 5-minute mayfly teardown, 256MB JS heap. `--nuclear` opts into `--single-process`.
+- **Tab journal + lazy restore** — kills become resume points, not disasters. `bwb --setup` prints a survival guide.
 
-### Bug Fixes
-- **`browser_back` rewritten** — native CDP history navigation (the `Page.goBack` call doesn't exist in bundled CDP 1.3; the old `history.back()` JS hack is gone). Verified with real two-step back navigation.
-- **`browser_act` precision fixes** — navigation regex no longer swallows compound instructions ("go to X and read the title" works), "fill X with Y" vs "type Y in X" no longer swap target/text, and `search` can't hijack "fill search with X"
-- **`killOrphanedChrome` safety** — graceful SIGTERM→SIGKILL, now scoped to bwb's own profile so it never kills another agent's browser
-- **`browser_restart` hygiene** — watch listeners can't outlive the dying protocol
-- **`browser_status` accuracy** — uses the real bound port, no more hardcoded 9222 poke
+### Breaking
+- `browser_title` + `browser_url` folded into `browser_status.targets`. Still 26 tools — that's now a release gate.
 
-*Fixes from the PR #1 code review by @netzro (Hermes Agent) are incorporated and credited in the [changelog](./CHANGELOG.md).*
+*Full story in the [changelog](./CHANGELOG.md). Older releases documented there too.*
 
 ---
 
@@ -111,7 +131,7 @@ Every screenshot is saved to disk (Android: `/storage/emulated/0/Download/bwb-sc
 ```bash
 npm install -g bwb-browser
 bwb --version
-# → bwb-browser 3.2.0
+# → bwb-browser 4.0.0
 ```
 
 Done. If you have Chrome/Chromium anywhere on your system, bwb finds it. No config files. No environment variables. Just works.
@@ -135,12 +155,10 @@ bwb
 | **`browser_watch`** | 🔥 Live event capture — console, network, errors, navigation |
 | **`browser_diagnose`** | 🔥 Full page health check — perf, errors, broken images, score |
 | **`browser_fingerprint`** | 🔥 Realistic browser profile for testing |
-| `browser_goto` | Navigate to a URL |
+| `browser_goto` | Navigate — static-first, escalates to browser with reason |
 | `browser_screenshot` | Take a screenshot — whole page, viewport, or a single element via `selector` |
 | `browser_html` | Get page/selector HTML |
 | `browser_text` | Get page/selector text |
-| `browser_title` | Get page title |
-| `browser_url` | Get current URL |
 | `browser_back` | Go back in history |
 | `browser_click` | Click an element (native CDP) |
 | `browser_fill` | Fill an input field (native CDP) |
@@ -155,7 +173,9 @@ bwb
 | `browser_saveCookies` | Save session to disk |
 | `browser_loadCookies` | Load session from disk |
 | `browser_listSessions` | List saved sessions |
-| `browser_status` | Browser connection info |
+| `browser_download` | Download media (needs system yt-dlp, consent-gated) |
+| `browser_export` | Export md/txt/html (pdf/docx/pptx need pip libs, consent-gated) |
+| `browser_status` | Status + live resources + active profile |
 | `browser_restart` | Restart the browser |
 
 ---
@@ -196,13 +216,13 @@ See [AGENTS.md](./AGENTS.md) for copy-paste configs for each one.
 
 ## The Backstory
 
-I built this because I was tired of every browser automation tool assuming you have 400MB to spare and a desktop-class machine. I work from my phone sometimes. Termux exists. Why shouldn't browser automation work there too?
+Every browser automation tool assumes you have 400MB to spare and a desktop-class machine. That assumption excludes phones, cheap VPS boxes, Raspberry Pis, and CI runners — most of the world's computers.
 
-So I did what any reasonable person would do: I ignored all the existing solutions and wrote my own, using nothing but raw CDP — the protocol Chrome speaks natively. No wrappers. No abstractions. Just JSON messages over WebSocket.
+bwb is engineered against the hardest constraint first: **a memory-pressured device where every megabyte is contested.** No bundled browser. No wrapper frameworks. Just raw CDP — the protocol Chrome speaks natively — plus a static-fetch ladder so Chromium only starts when JavaScript demands it. Mobile-first isn't a feature here. It's the design spec everything else has to survive.
 
-The result is 76KB of source code that does what 400MB of dependencies do. It's not _better_ code — it's _less_ code. And sometimes less is all you need.
+The result is ~136KB of source that does what 400MB of dependencies do. Not better code — less code, held to budgets: 26 tools max, 60 kB tarball max, zero native modules. Constraints are features.
 
-*— Krish Tiwari ([@krshforever](https://github.com/krshforever)), somewhere on an Indian train, writing code on a phone*
+*— Krish Tiwari ([@krshforever](https://github.com/krshforever))*
 
 ---
 

package/lib/browser.mjs

@@ -31,8 +31,55 @@ export const cfg = {
   screenshotsDir: "",
   navTimeout: 30000,
   browserPath: null,
+  lean: null, // null = auto (Termux/1GB heuristics); true/false forces
+  nuclear: false, // --single-process: max RAM saving, min stability. Opt-in only.
+  idleMs: null, // null = auto (5min lean, off desktop); 0 = never teardown
+  tabMax: null, // null = auto (3 lean, unlimited desktop); 0 = unlimited
+  attachPort: 0, // 0 = off (spawn own browser). N = attach to existing
+                 // browser's CDP port (e.g. 9222) — never spawns, never kills.
 };
 
+// True when connected to a foreign (user-owned) browser via --attach-port.
+// Attached browsers are never spawned, killed, or journal-restored —
+// bwb is a guest there. Tab hibernation still works but closes REAL tabs.
+export let attached = false;
+
+// ─── Environment ─────────────────────────────────────────────────────────────
+
+export function isTermux() {
+  return Boolean(
+    process.env.TERMUX_VERSION ||
+    process.env.PREFIX?.includes("com.termux") ||
+    process.env.HOME?.includes("com.termux")
+  );
+}
+
+// ─── Idle Mayfly (auto-teardown) ─────────────────────────────────────────────
+
+let idleTimer = null;
+let idleSuppressed = false; // true while browser_watch is recording
+
+export function setIdleSuppressed(suppressed) {
+  idleSuppressed = suppressed;
+  if (suppressed) disarmIdle();
+  else pokeActivity();
+}
+
+export function disarmIdle() {
+  if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+}
+
+/** Reset the mayfly timer. Called after every tool call via the server wrapper. */
+export function pokeActivity() {
+  disarmIdle();
+  if (!cfg.idleMs || idleSuppressed || !browser || browserExited) return;
+  idleTimer = setTimeout(() => {
+    idleTimer = null;
+    if (!idleSuppressed) stopBrowser("idle-timeout").catch(() => {});
+  }, cfg.idleMs);
+  if (idleTimer.unref) idleTimer.unref(); // never hold the MCP process open
+}
+
 // ─── Kill Orphaned Chrome (Termux-safe) ────────────────────────────────────────
 
 // `fuser -k` and `lsof` can't read /proc/net/tcp on Termux/Android (permission denied).
@@ -79,8 +126,11 @@ export function findBrowserPath(cliPath) {
       "chromium-browser",
       "chromium",
       "google-chrome-stable",
+      "brave-browser",
+      "brave",
       "/usr/bin/google-chrome",
       "/usr/bin/chromium-browser",
+      "/usr/bin/brave-browser",
       "/snap/bin/chromium",
     ],
     darwin: [
@@ -139,6 +189,34 @@ export async function ensureBrowser() {
   browserStartup = new Promise((res, rej) => { startResolve = res; startReject = rej; });
   browserStartup.catch(() => { browserStartup = null; });
 
+  // ─── Attach mode: guest on someone else's browser ──────────────────────
+  // No spawn, no orphan-kill, no journal restore (never navigate a user's
+  // tabs on connect). ensureDefaultTab() registers whatever is already open.
+  if (cfg.attachPort) {
+    (async () => {
+      try {
+        const port = cfg.attachPort;
+        const cdp = await CDP({ port });
+        protocol = cdp;
+        browser = null;
+        attached = true;
+        actualCdpPort = port;
+        startResolve(cdp);
+        pokeActivity();
+      } catch (err) {
+        browserStartup = null;
+        browserExited = true;
+        attached = false;
+        startReject(new Error(
+          `Attach failed: no browser listening on CDP port ${cfg.attachPort} (${err.message}). ` +
+          `Launch one with --remote-debugging-port=${cfg.attachPort} first.`
+        ));
+      }
+    })();
+    return browserStartup;
+  }
+  attached = false;
+
   (async () => {
     try {
       const browserPath = assertBrowserExists(cfg.browserPath);
@@ -155,6 +233,7 @@ export async function ensureBrowser() {
         "--disable-software-rasterizer",
         "--remote-debugging-port=" + debugPort,
         "--user-data-dir=" + cfg.userDataDir,
+        ...leanArgs(),
       ];
 
       if (!cfg.headless) args.shift();
@@ -199,7 +278,13 @@ export async function ensureBrowser() {
           CDP({ port: actualCdpPort })
             .then((cdp) => {
               protocol = cdp;
-              startResolve(cdp);
+              // Awaited, not fire-and-forget: callers must see the restored
+              // working set, not a blank tab that later jumps. Capped + fast.
+              (async () => {
+                try { await restoreJournalTabs(); } catch {}
+                startResolve(cdp);
+                pokeActivity();
+              })();
             })
             .catch((err) => {
               try { browser.kill("SIGKILL"); } catch {}
@@ -218,6 +303,58 @@ export async function ensureBrowser() {
   return browserStartup;
 }
 
+// ─── Lean Flags (v4 survival profile) ─────────────────────────────────────────
+// Compat flags above make Chromium RUN on Termux. These make it SURVIVE:
+// capped renderers, silenced background services, bounded cache + JS heap.
+// --single-process stays behind --nuclear: biggest saving, weakest stability.
+
+function leanArgs() {
+  if (!cfg.lean) return [];
+  const flags = [
+    "--renderer-process-limit=1",
+    "--disable-background-networking",
+    "--disable-component-update",
+    "--disable-sync",
+    "--mute-audio",
+    "--disable-features=Translate",
+    "--disk-cache-size=67108864",
+    "--js-flags=--max-old-space-size=256",
+  ];
+  if (cfg.nuclear) flags.push("--single-process", "--no-zygote");
+  return flags;
+}
+
+// ─── Stop (graceful mayfly teardown — journal keeps the working set) ─────────
+
+export async function stopBrowser(reason = "manual") {
+  if (cleaningUp) return { status: "busy" };
+  cleaningUp = true;
+  disarmIdle();
+  try {
+    if (protocol) {
+      try { await protocol.close(); } catch {}
+      protocol = null;
+    }
+    // Attached browsers are foreign — disconnect only, never kill.
+    if (browser && !attached) {
+      try { browser.kill("SIGTERM"); } catch {}
+      await new Promise(r => setTimeout(r, 1500));
+      try { browser.kill("SIGKILL"); } catch {}
+      browser = null;
+    }
+  } catch {}
+  browserExited = true; // next ensureBrowser() respawns fresh + restores journal
+  actualCdpPort = null;
+  attached = false;
+  browserStartup = null;
+  cleaningUp = false;
+  try {
+    const { clearTabs } = await import("./tabs.mjs");
+    clearTabs();
+  } catch {}
+  return { status: "stopped", reason };
+}
+
 // ─── Restart ──────────────────────────────────────────────────────────────────
 
 export async function restartBrowser() {
@@ -229,7 +366,9 @@ export async function restartBrowser() {
       try { await protocol.close(); } catch {}
       protocol = null;
     }
-    if (browser) {
+    // Attached browsers are foreign — disconnect only, never kill.
+    // Next ensureBrowser() re-attaches (no journal restore in attach mode).
+    if (browser && !attached) {
       browser.kill("SIGTERM");
       await new Promise(r => setTimeout(r, 2000));
       try { browser.kill("SIGKILL"); } catch {}
@@ -246,6 +385,18 @@ export async function restartBrowser() {
   return { status: "restarted" };
 }
 
+// ─── Journal Restore (post-kill resurrection — lazy, capped) ─────────────────
+// Reopens the journaled working set after a fresh spawn (LMK kill, mayfly
+// teardown, restart). First entry navigates now; the rest become placeholders
+// woken on switchTab. Never re-spikes memory at startup to "restore".
+
+async function restoreJournalTabs() {
+  try {
+    const tabs = await import("./tabs.mjs");
+    await tabs.restoreJournal();
+  } catch {}
+}
+
 // ─── Screenshot Helper ────────────────────────────────────────────────────────
 
 export function saveScreenshot(base64Data) {

package/lib/fetch.mjs

@@ -0,0 +1,127 @@
+/**
+ * bwb-browser — Static-first fetch (v4 fetch ladder, rung 1)
+ *
+ * Plain HTTP + Readability extraction. Zero Chromium, zero new persistent RAM:
+ * heavy deps are lazy-imported inside the function, so the MCP process pays
+ * nothing until the first static fetch. Called by browser_goto before CDP.
+ */
+
+const FETCH_MAX_BYTES = 2_000_000; // never buffer more than 2MB per page
+const MIN_TEXT_CHARS = 500; // below this + JS markers => probably a JS shell
+
+// Framework shells / client-rendered markers — presence + thin text = escalate
+const JS_MARKERS = [
+  'id="root"', "id='root'", 'id="app"', "id='app'",
+  "__NEXT_DATA__", "ng-app", "ng-version", "data-reactroot",
+  "__NUXT__", "ember-view", "data-svelte", "_astro",
+];
+// Login / auth walls — static fetch can't pass, but the browser (sessions) might
+const AUTH_MARKERS = ["password", "sign in", "log in", "login", "captcha"];
+
+const TEXT_TYPES = ["text/html", "text/plain", "application/xhtml+xml"];
+
+/**
+ * Fetch + extract without Chromium.
+ * @returns {mode:'static',...} | {mode:'escalate', reason} | {mode:'error', error}
+ */
+export async function staticFetch(url, { timeout = 15000 } = {}) {
+  let res;
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeout);
+    try {
+      res = await fetch(url, {
+        signal: ctrl.signal,
+        redirect: "follow",
+        headers: {
+          "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 bwb-static/4.0",
+          Accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.1",
+        },
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    // Network-level failure — CDP shares the same network, but surfaces
+    // better diagnostics (diagnosePage). Escalate rather than hard-fail.
+    return { mode: "escalate", reason: `static fetch failed (${err.name}): ${err.message}` };
+  }
+
+  // Auth walls: the browser (with sessions/cookies) may pass where fetch can't
+  if (res.status === 401 || res.status === 403 || res.status === 429) {
+    return { mode: "escalate", reason: `HTTP ${res.status} — possible auth wall / rate limit` };
+  }
+  if (!res.ok) {
+    // Dead URL — CDP won't resurrect it. Don't spawn Chromium for a 404.
+    return { mode: "error", error: `HTTP ${res.status} ${res.statusText} for ${url}` };
+  }
+
+  const contentType = (res.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
+  if (contentType && !TEXT_TYPES.some((t) => contentType.startsWith(t))) {
+    return { mode: "escalate", reason: `non-text content (${contentType || "unknown"})` };
+  }
+
+  // Bounded body read — never buffer a whole ISO / stream
+  let html = "";
+  try {
+    const reader = res.body.getReader();
+    let received = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      received += value.length;
+      if (received > FETCH_MAX_BYTES) {
+        try { await reader.cancel(); } catch {}
+        return { mode: "escalate", reason: "page exceeds 2MB static cap — needs browser" };
+      }
+      html += Buffer.from(value).toString("utf8");
+    }
+  } catch (err) {
+    return { mode: "escalate", reason: `body read failed: ${err.message}` };
+  }
+
+  if (contentType.startsWith("text/plain")) {
+    const text = html.trim();
+    if (text.length < MIN_TEXT_CHARS) {
+      return { mode: "escalate", reason: "plain-text body too thin to trust" };
+    }
+    return { mode: "static", title: "", text, finalUrl: res.url, bytes: html.length, confidence: "high" };
+  }
+
+  // HTML → Readability (lazy deps: zero cost until first use)
+  let article;
+  try {
+    const { parseHTML } = await import("linkedom");
+    const { Readability } = await import("@mozilla/readability");
+    const { document } = parseHTML(html);
+    article = new Readability(document).parse();
+  } catch (err) {
+    return { mode: "escalate", reason: `extraction crashed: ${err.message}` };
+  }
+  if (!article || !(article.textContent || "").trim()) {
+    return { mode: "escalate", reason: "no readable article found" };
+  }
+
+  const text = article.textContent.trim().replace(/\n{3,}/g, "\n\n");
+  const lower = html.toLowerCase();
+  const hasJsShell = JS_MARKERS.some((m) => lower.includes(m.toLowerCase()));
+  const looksAuthed = AUTH_MARKERS.some((m) => lower.includes(m)) && text.length < MIN_TEXT_CHARS;
+
+  if (text.length < MIN_TEXT_CHARS && (hasJsShell || looksAuthed)) {
+    return {
+      mode: "escalate",
+      reason: looksAuthed && !hasJsShell
+        ? "thin text behind possible login wall"
+        : "thin text + JS shell markers — needs rendering",
+    };
+  }
+
+  return {
+    mode: "static",
+    title: article.title || "",
+    text,
+    finalUrl: res.url,
+    bytes: html.length,
+    confidence: text.length >= MIN_TEXT_CHARS ? "high" : "medium",
+  };
+}

package/lib/setup.mjs

@@ -305,9 +305,32 @@ export function runSetup() {
   }
 
   console.log('  🚀 Ready to go! Try: browser_status\n');
+  printSurvivalGuide();
   return { configured: configured.length, alreadyDone: alreadyDone.length, errors: errors.length };
 }
 
+// ─── Survival Guide (v4: OOM is the enemy, not setup) ───────────────────────
+// WakeLock + battery exemption don't stop LMK — footprint does. One-time notes.
+
+function printSurvivalGuide() {
+  const termux = Boolean(process.env.TERMUX_VERSION
+    || process.env.PREFIX?.includes('com.termux')
+    || process.env.HOME?.includes('com.termux'));
+  console.log('  ─── Survival guide (read once) ───────────────────────');
+  console.log('  v4 is static-first: plain pages never spawn Chromium.');
+  console.log('  Lean profile auto-enables on Termux (cap 3 tabs, 5-min mayfly).');
+  console.log('  Every tool response carries a [bwb resources] footer —');
+  console.log('  when it reads critical, bwb sheds tabs itself and says so.');
+  if (termux) {
+    console.log('  Termux overnight runs:');
+    console.log('    • termux-wake-lock (keeps CPU awake, does NOT stop LMK)');
+    console.log('    • Exempt Termux from battery optimization (Android Settings)');
+    console.log('    • The rest is footprint: fewer tabs, static-first,');
+    console.log('      journal restores your working set if Android still kills.');
+  }
+  console.log();
+}
+
 function getVersion() {
   try {
     const pkg = path.resolve(__dirname, '..', 'package.json');