bwb-browser 3.2.0 → 4.0.0

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 |

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) | 🐌 | 🐌 |
 
 ---
 

package/lib/browser.mjs

@@ -31,8 +31,48 @@ 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
 };
 
+// ─── 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).
@@ -155,6 +195,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 +240,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 +265,56 @@ 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;
+    }
+    if (browser) {
+      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;
+  browserStartup = null;
+  cleaningUp = false;
+  try {
+    const { clearTabs } = await import("./tabs.mjs");
+    clearTabs();
+  } catch {}
+  return { status: "stopped", reason };
+}
+
 // ─── Restart ──────────────────────────────────────────────────────────────────
 
 export async function restartBrowser() {
@@ -246,6 +343,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');

package/lib/tabs.mjs

@@ -8,6 +8,49 @@
 
 import CDP from "chrome-remote-interface";
 import { ensureBrowser, protocol, actualCdpPort, cfg } from "./browser.mjs";
+import { writeFileSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+// ─── Tab Journal (working-set survival across LMK kills / mayfly teardown) ───
+// Tiny JSON append on every mutation. Journal is the truth the next fresh
+// browser restores from — cookies live in user-data-dir, tab URLs live here.
+
+function journalPath() {
+  if (!cfg.userDataDir) return null;
+  return join(cfg.userDataDir, "bwb-tabs.json");
+}
+
+function saveJournal() {
+  try {
+    const path = journalPath();
+    if (!path) return;
+    const entries = [];
+    for (const [id, tab] of tabs) {
+      if (tab.url && tab.url !== "about:blank") {
+        entries.push({ url: tab.url, title: tab.title || "", active: id === activeTabId });
+      }
+    }
+    writeFileSync(path, JSON.stringify(entries));
+  } catch {}
+}
+
+function loadJournal() {
+  try {
+    const path = journalPath();
+    if (!path || !existsSync(path)) return [];
+    const entries = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(entries) ? entries.filter((e) => e && e.url) : [];
+  } catch {
+    return [];
+  }
+}
+
+// Live-tab cap: 0/unset = unlimited (desktop). Lean profiles set 3.
+function liveCount() {
+  let n = 0;
+  for (const tab of tabs.values()) if (!tab.hibernated) n++;
+  return n;
+}
 
 // ─── Tab State ───────────────────────────────────────────────────────────────
 
@@ -47,6 +90,7 @@ export async function getActiveProtocol() {
 
   if (activeTabId && tabs.has(activeTabId)) {
     const tab = tabs.get(activeTabId);
+    if (tab.hibernated) return wakeTab(activeTabId);
     if (tab.protocol) return tab.protocol;
   }
 
@@ -54,6 +98,72 @@ export async function getActiveProtocol() {
   return protocol;
 }
 
+/**
+ * Hibernate a tab: URL stays in the journal + visible in listTabs, but the
+ * renderer is closed and memory freed. Woken transparently on switchTab.
+ * Never hibernates the active tab — caller must switch away first.
+ */
+export async function hibernateTab(targetId) {
+  const id = targetId || [...tabs.keys()].find((k) => k !== activeTabId && !tabs.get(k)?.hibernated);
+  if (!id || !tabs.has(id)) return null;
+  const tab = tabs.get(id);
+  if (tab.hibernated) return { id, hibernated: true };
+  const port = actualCdpPort || cfg.port;
+  try { await CDP.Close({ id, port }); } catch {}
+  if (tab.protocol && tab.protocol !== protocol) {
+    try { await tab.protocol.close(); } catch {}
+  }
+  tabs.set(id, { protocol: null, title: tab.title, url: tab.url, hibernated: true });
+  saveJournal();
+  return { id, hibernated: true, url: tab.url };
+}
+
+/** Wake a hibernated tab: fresh target, journaled URL re-navigated. */
+async function wakeTab(targetId) {
+  const tab = tabs.get(targetId);
+  if (!tab || !tab.hibernated) return tab?.protocol || protocol;
+  const port = actualCdpPort || cfg.port;
+  const info = await CDP.New({ port, url: tab.url || "about:blank" });
+  const newProtocol = await CDP({ target: info.id, port });
+  tabs.delete(targetId);
+  tabs.set(info.id, { protocol: newProtocol, title: info.title || tab.title, url: info.url || tab.url });
+  if (activeTabId === targetId) activeTabId = info.id;
+  saveJournal();
+  return newProtocol;
+}
+
+/**
+ * Restore the journaled working set after a fresh spawn. First entry
+ * navigates now; the rest become about:blank placeholders woken on switch.
+ * Capped at cfg.tabMax so restore never re-spikes memory at startup.
+ */
+export async function restoreJournal() {
+  const entries = loadJournal();
+  if (!entries.length) return false;
+  await ensureDefaultTab();
+  const cap = cfg.tabMax && cfg.tabMax > 0 ? cfg.tabMax : entries.length;
+  const wanted = entries.slice(0, Math.max(cap, 1));
+  const port = actualCdpPort || cfg.port;
+  let first = true;
+  for (const entry of wanted) {
+    if (first) {
+      first = false;
+      try {
+        await protocol.Page.navigate({ url: entry.url });
+        syncActiveTab(entry.title, entry.url);
+      } catch {}
+      continue;
+    }
+    try {
+      const info = await CDP.New({ port, url: "about:blank" });
+      const newProtocol = await CDP({ target: info.id, port });
+      tabs.set(info.id, { protocol: newProtocol, title: entry.title || "", url: "", pendingUrl: entry.url });
+    } catch {}
+  }
+  saveJournal();
+  return true;
+}
+
 // ─── Create Tab ──────────────────────────────────────────────────────────────
 
 /**
@@ -63,6 +173,16 @@ export async function getActiveProtocol() {
 export async function createTab(url) {
   await ensureDefaultTab();
 
+  // Live-tab cap: hibernate the oldest non-active tab instead of growing
+  // renderers until Android LMK notices. Journal keeps everything restorable.
+  if (cfg.tabMax && cfg.tabMax > 0) {
+    while (liveCount() >= cfg.tabMax) {
+      const victim = [...tabs.keys()].find((k) => k !== activeTabId && !tabs.get(k)?.hibernated);
+      if (!victim) break;
+      await hibernateTab(victim);
+    }
+  }
+
   const port = actualCdpPort || cfg.port;
   const info = await CDP.New({ port, url: url || "about:blank" });
 
@@ -70,6 +190,7 @@ export async function createTab(url) {
   const newProtocol = await CDP({ target: info.id, port });
   tabs.set(info.id, { protocol: newProtocol, title: info.title || "", url: info.url || url || "" });
   activeTabId = info.id;
+  saveJournal();
 
   return { id: info.id, title: info.title || "", url: info.url || "" };
 }
@@ -103,6 +224,7 @@ export async function closeTab(targetId) {
   if (activeTabId === id) {
     activeTabId = tabs.keys().next().value;
   }
+  saveJournal();
 
   return { closed: id, activeTab: activeTabId };
 }
@@ -110,17 +232,35 @@ export async function closeTab(targetId) {
 // ─── Switch Tab ──────────────────────────────────────────────────────────────
 
 /**
- * Switches to a different tab by targetId.
+ * Switches to a different tab by targetId. Hibernated tabs and restored
+ * placeholders wake transparently (async navigation on first switch).
  */
-export function switchTab(targetId) {
+export async function switchTab(targetId) {
   if (!targetId) throw new Error("No targetId provided");
   if (!tabs.has(targetId)) {
     throw new Error(`Tab not found: ${targetId}`);
   }
 
-  activeTabId = targetId;
   const tab = tabs.get(targetId);
-  return { id: targetId, title: tab.title, url: tab.url };
+  if (tab.hibernated) {
+    await wakeTab(targetId);
+    const woken = tabs.get(activeTabId);
+    return { id: activeTabId, title: woken?.title, url: woken?.url, woken: true };
+  }
+  activeTabId = targetId;
+  if (tab.pendingUrl) {
+    const url = tab.pendingUrl;
+    delete tab.pendingUrl;
+    try {
+      const cdp = tab.protocol || protocol;
+      const { Page } = cdp;
+      await Page.navigate({ url });
+      tab.url = url;
+    } catch {}
+  }
+  saveJournal();
+  const current = tabs.get(activeTabId);
+  return { id: activeTabId, title: current?.title, url: current?.url };
 }
 
 // ─── List Tabs ───────────────────────────────────────────────────────────────
@@ -136,6 +276,8 @@ export function listTabs() {
       title: tab.title,
       url: tab.url,
       active: id === activeTabId,
+      ...(tab.hibernated ? { hibernated: true } : {}),
+      ...(tab.pendingUrl ? { pendingUrl: tab.pendingUrl } : {}),
     });
   }
   return result;
@@ -161,5 +303,6 @@ export function syncActiveTab(title, url) {
     const tab = tabs.get(activeTabId);
     if (title) tab.title = title;
     if (url) tab.url = url;
+    saveJournal();
   }
 }

package/lib/vigil.mjs

@@ -0,0 +1,77 @@
+/**
+ * bwb-browser — Resource vigilance (v4)
+ *
+ * Pure measurement + policy. No imports from tabs/browser (avoid cycles) —
+ * the server.mjs response wrapper executes the actions assess() recommends.
+ * MCP can't push, so every tool response carries a ~100-byte footer and the
+ * watcher stream carries memory samples. That IS the "instant" channel.
+ */
+
+import { execSync } from "child_process";
+
+// 1GB-box budgets (MB) when lean; roomier desktop defaults otherwise.
+// Override any via BWB_WARN_MB / BWB_CRIT_MB. resolveBudgets() is called
+// by server.mjs after config — before that, lean-safe values apply.
+export let WARN_MB = parseInt(process.env.BWB_WARN_MB || "300", 10);
+export let CRIT_MB = parseInt(process.env.BWB_CRIT_MB || "450", 10);
+
+export function resolveBudgets(isLean) {
+  if (process.env.BWB_WARN_MB !== undefined) WARN_MB = parseInt(process.env.BWB_WARN_MB, 10);
+  else WARN_MB = isLean ? 300 : 1024;
+  if (process.env.BWB_CRIT_MB !== undefined) CRIT_MB = parseInt(process.env.BWB_CRIT_MB, 10);
+  else CRIT_MB = isLean ? 450 : 1536;
+}
+
+const MB = 1024 * 1024;
+
+function selfMb() {
+  return Math.round(process.memoryUsage().rss / MB);
+}
+
+// Sum RSS of a pid + its descendants via ps. Null when unmeasurable.
+function treeMb(rootPid) {
+  if (!rootPid) return null;
+  try {
+    const out = execSync("ps -o pid=,ppid=,rss= -e", { encoding: "utf8", timeout: 3000 });
+    const procs = out.trim().split("\n").map((l) => {
+      const [pid, ppid, rss] = l.trim().split(/\s+/).map(Number);
+      return { pid, ppid, rss };
+    });
+    const kids = new Set([Number(rootPid)]);
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const p of procs) {
+        if (kids.has(p.ppid) && !kids.has(p.pid)) { kids.add(p.pid); grew = true; }
+      }
+    }
+    let kb = 0;
+    for (const p of procs) if (kids.has(p.pid) && Number.isFinite(p.rss)) kb += p.rss;
+    return Math.round(kb / 1024);
+  } catch {
+    return null;
+  }
+}
+
+/** Snapshot: {mcpMb, chromiumMb|null, tabCount} */
+export function sampleResources(browserPid, tabCount = 0) {
+  return { mcpMb: selfMb(), chromiumMb: treeMb(browserPid), tabCount };
+}
+
+/**
+ * Policy verdict: 'ok' | 'watch' | 'critical'.
+ * critical = shed load NOW (hibernate tabs → teardown). watch = warn only.
+ */
+export function assess(sample) {
+  const total = (sample.chromiumMb || 0) + sample.mcpMb;
+  if (total >= CRIT_MB) return "critical";
+  if (total >= WARN_MB) return "watch";
+  return "ok";
+}
+
+/** ~100-byte footer appended as an extra text block to every tool response. */
+export function resourceFooter(sample, note = "") {
+  const c = sample.chromiumMb === null ? "browser:off" : `browser:${sample.chromiumMb}MB`;
+  const trend = assess(sample);
+  return `[bwb resources] mcp:${sample.mcpMb}MB ${c} tabs:${sample.tabCount} state:${trend}${note ? " " + note : ""}]`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bwb-browser",
-  "version": "3.2.0",
-  "description": "Browser Without Bloat — 76KB MCP server that gives AI agents browser superpowers. Natural language interaction, live event watching, persistent sessions, multi-tab. Runs on Termux/Android, desktop, and CI. Zero heavy dependencies.",
+  "version": "4.0.0",
+  "description": "Browser Without Bloat — lightweight MCP server that gives AI agents browser superpowers. Static-first fetch ladder (Chromium only when JS demands it), lean profiles for Termux/1GB VPS, resource vigilance, tab journaling. Runs anywhere. Stays lean like air.",
   "bin": {
     "bwb": "bin/bwb"
   },
@@ -62,6 +62,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "chrome-remote-interface": "^0.34.0",
-    "zod": "^3.22.0"
+    "zod": "^3.22.0",
+    "@mozilla/readability": "^0.6.0",
+    "linkedom": "^0.18.13"
   }
 }

package/server.mjs

@@ -12,20 +12,31 @@
  *   --headless / BWB_HEADLESS               — Run headless (default: true)
  *   --screenshots-dir / BWB_SCREENSHOTS_DIR — Directory for saved screenshots
  *   --timeout / BWB_NAV_TIMEOUT             — Navigation timeout in ms (default: 30000)
+ *   --lean / BWB_LEAN                       — Survival profile: capped renderers,
+ *                                             silenced background services, tab cap,
+ *                                             mayfly teardown (default: auto on Termux)
+ *   --nuclear / BWB_NUCLEAR                 — Add --single-process (max saving,
+ *                                             min stability). Opt-in only.
+ *   --idle / BWB_IDLE_MS                    — Mayfly teardown after N ms idle
+ *                                             (default: 5min lean, off desktop)
+ *   --tab-max / BWB_TAB_MAX                 — Live-tab cap, oldest hibernated
+ *                                             (default: 3 lean, unlimited desktop)
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import CDP from "chrome-remote-interface";
+import { execSync } from "child_process";
 import { mkdirSync, readFileSync, existsSync } from "fs";
 import { homedir, platform } from "os";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 
 import {
-  ensureBrowser, restartBrowser, saveScreenshot,
+  ensureBrowser, restartBrowser, stopBrowser, saveScreenshot,
   cfg, browser, browserExited, actualCdpPort,
+  isTermux, pokeActivity, setIdleSuppressed,
 } from "./lib/browser.mjs";
 
 // ─── --setup mode ──────────────────────────────────────────────────
@@ -41,8 +52,12 @@ import {
 
 import {
   getActiveProtocol, createTab, closeTab, switchTab, listTabs, syncActiveTab, clearTabs,
+  hibernateTab,
 } from "./lib/tabs.mjs";
 
+import { staticFetch } from "./lib/fetch.mjs";
+import { sampleResources, assess, resourceFooter, resolveBudgets } from "./lib/vigil.mjs";
+
 import { saveSession, loadSession, listSessions } from "./lib/session.mjs";
 import { diagnosePage } from "./lib/diagnose.mjs";
 import { applyRealisticProfile } from "./lib/fingerprint.mjs";
@@ -68,6 +83,10 @@ function parseArgs() {
       case "--headless": cliCfg.headless = args[++i] !== "false"; break;
       case "--screenshots-dir": cliCfg.screenshotsDir = args[++i]; break;
       case "--timeout": cliCfg.navTimeout = parseInt(args[++i], 10); break;
+      case "--lean": cliCfg.lean = args[++i] !== "false"; break;
+      case "--nuclear": cliCfg.nuclear = args[++i] !== "false"; break;
+      case "--idle": cliCfg.idleMs = parseInt(args[++i], 10); break;
+      case "--tab-max": cliCfg.tabMax = parseInt(args[++i], 10); break;
       case "--version": console.log(`bwb-browser ${BWB_VERSION}`); process.exit(0);
       case "--help": printHelp(); process.exit(0);
     }
@@ -77,12 +96,12 @@ function parseArgs() {
 
 function printHelp() {
   console.log(`
-bwb-browser v${BWB_VERSION} — Browser Without Bloat
+ bwb-browser v${BWB_VERSION} — Browser Without Bloat
 
-Browser automation for AI agents. 76KB. 26 tools. Zero heavy dependencies.
-Uses raw CDP — no Playwright, no Puppeteer, no 400MB downloads.
+Browser automation for AI agents. Static-first, lean like air. 26 tools.
+Raw CDP — no Playwright, no Puppeteer. Chromium starts only when JS demands it.
 
-Built on Termux/Android. Runs everywhere. Weighs nothing.
+Built on Termux/Android. Runs everywhere — including 1GB VPS boxes.
 
 USAGE:
   bwb [options]
@@ -94,18 +113,21 @@ OPTIONS:
   --headless <bool>        Run headless (default: true)
   --screenshots-dir <path> Directory to save screenshots
   --timeout <ms>           Navigation timeout in ms (default: 30000)
+  --lean <bool>            Survival profile (default: auto on Termux)
+  --nuclear                Add --single-process (max saving, min stability)
+  --idle <ms>              Mayfly teardown after N ms idle (default: 5min lean)
+  --tab-max <n>            Live-tab cap, oldest hibernated (default: 3 lean)
   --version                Print version
   --help                   Show this help
 
 TOOLS (26):
   CORE BROWSING:
-    browser_goto              Navigate to a URL
+    browser_goto              Navigate (static-first, escalates to browser)
     browser_screenshot        Take a screenshot
     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
+    (title/url folded into browser_status — v4 breaking change)
 
   INTERACTION:
     browser_click             Click an element
@@ -116,7 +138,7 @@ TOOLS (26):
 
   🔥 ADVANCED:
     browser_act               Natural language page interaction (one tool does it all)
-    browser_watch             Live page event capture (console, network)
+    browser_watch             Live page event capture (console, network + resources)
     browser_diagnose          Full page health diagnostic
     browser_fingerprint       Realistic browser profile for testing
     browser_waitForSelector   Wait for element to appear/disappear
@@ -124,7 +146,7 @@ TOOLS (26):
   MULTI-TAB:
     browser_newTab            Create a new tab
     browser_closeTab          Close a tab
-    browser_switchTab         Switch to a different tab
+    browser_switchTab         Switch to a tab (hibernated tabs wake)
     browser_listTabs          List all open tabs
 
   SESSION:
@@ -132,8 +154,12 @@ TOOLS (26):
     browser_loadCookies       Load session cookies from disk
     browser_listSessions      List saved sessions
 
+  ON-DEMAND (verbs ship, weight doesn't — backends install on consent):
+    browser_download          Download media (needs system yt-dlp)
+    browser_export            Export md/txt/html (pdf/docx/pptx need pip libs)
+
   LIFECYCLE:
-    browser_status            Browser connection status
+    browser_status            Status + live resources + active profile
     browser_restart           Restart the browser
 
 If bwb saves you time or money, consider supporting development:
@@ -183,6 +209,24 @@ cfg.screenshotsDir = cfg.screenshotsDir || process.env.BWB_SCREENSHOTS_DIR || ((
   return join(homedir(), "bwb-screenshots");
 })();
 cfg.navTimeout = cfg.navTimeout || parseInt(process.env.BWB_NAV_TIMEOUT || "30000", 10);
+// v4 survival defaults: lean auto-detects Termux; mayfly + tab cap follow lean
+// unless explicitly overridden. Desktop behavior unchanged (all off).
+if (cfg.lean === null || cfg.lean === undefined) {
+  if (process.env.BWB_LEAN !== undefined) cfg.lean = process.env.BWB_LEAN !== "false";
+  else cfg.lean = isTermux();
+}
+if (cfg.nuclear === undefined || cfg.nuclear === null) {
+  cfg.nuclear = process.env.BWB_NUCLEAR === "true";
+}
+if (cfg.idleMs === null || cfg.idleMs === undefined) {
+  if (process.env.BWB_IDLE_MS !== undefined) cfg.idleMs = parseInt(process.env.BWB_IDLE_MS, 10);
+  else cfg.idleMs = cfg.lean ? 5 * 60 * 1000 : 0;
+}
+if (cfg.tabMax === null || cfg.tabMax === undefined) {
+  if (process.env.BWB_TAB_MAX !== undefined) cfg.tabMax = parseInt(process.env.BWB_TAB_MAX, 10);
+  else cfg.tabMax = cfg.lean ? 3 : 0;
+}
+resolveBudgets(cfg.lean);
 
 try { mkdirSync(cfg.screenshotsDir, { recursive: true }); } catch {}
 
@@ -243,14 +287,29 @@ const tools = {
   // ═══════════════ CORE BROWSING ═══════════════
 
   browser_goto: {
-    description: "Navigate to a URL. Returns page title and URL.",
+    description: "Navigate to a URL. Returns page title and URL. v4: static-first — plain pages are fetched + extracted with zero Chromium; JS pages escalate to CDP automatically (see mode field).",
     schema: { url: z.string().describe("URL to navigate to") },
     handler: async ({ url }) => {
+      // Rung 1: static fetch. No browser spawned, no LMK risk, milliseconds.
+      const attempt = await staticFetch(url, { timeout: Math.min(cfg.navTimeout, 15000) });
+      if (attempt.mode === "static") {
+        syncActiveTab(attempt.title, attempt.finalUrl);
+        return { content: [{ type: "text", text: JSON.stringify({
+          mode: "static", title: attempt.title, url: attempt.finalUrl,
+          text: attempt.text, confidence: attempt.confidence,
+          note: "Served without Chromium. Need interaction/screenshots? Use browser_act / browser_screenshot — that escalates to the browser.",
+        }) }] };
+      }
+      if (attempt.mode === "error") {
+        // Dead URL — CDP shares the same network, don't spawn Chromium for a 404.
+        return { content: [{ type: "text", text: JSON.stringify({ mode: "error", error: attempt.error }) }] };
+      }
+      // Rung 2: escalate to Chromium (JS shell, auth wall, non-text).
       const cdp = await getActiveProtocol();
       const { Page, Runtime } = cdp;
       const result = await gotoUrl(Page, Runtime, url, cfg.navTimeout);
       syncActiveTab(result.title, result.url);
-      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      return { content: [{ type: "text", text: JSON.stringify({ ...result, mode: "browser", escalated: attempt.reason }) }] };
     },
   },
 
@@ -326,26 +385,6 @@ const tools = {
     },
   },
 
-  browser_title: {
-    description: "Get current page title.",
-    schema: {},
-    handler: async () => {
-      const { Runtime } = await getActiveProtocol();
-      const { result } = await Runtime.evaluate({ expression: "document.title" });
-      return { content: [{ type: "text", text: result?.value || "" }] };
-    },
-  },
-
-  browser_url: {
-    description: "Get current page URL.",
-    schema: {},
-    handler: async () => {
-      const { Runtime } = await getActiveProtocol();
-      const { result } = await Runtime.evaluate({ expression: "window.location.href" });
-      return { content: [{ type: "text", text: result?.value || "" }] };
-    },
-  },
-
   browser_back: {
     description: "Go back in browser history (like clicking the browser back button).",
     schema: {},
@@ -467,16 +506,21 @@ const tools = {
         await cdp.Runtime.enable();
         await cdp.Network.enable();
         setupWatch(events, cdp);
+        setIdleSuppressed(true); // recording in progress — mayfly must not teardown
         return { content: [{ type: "text", text: JSON.stringify({ status: "watching", events, msg: "Recording started. Poll to get events." }) }] };
       }
       if (action === "poll") {
         const snapshot = [...watchState.events];
         watchState.events = [];
-        return { content: [{ type: "text", text: JSON.stringify({ count: snapshot.length, events: snapshot }) }] };
+        // Resource vigilance rides the existing poll rhythm — no new mechanism.
+        let resources = null;
+        try { resources = sampleResources(browser?.pid, listTabs().filter((t) => !t.hibernated).length); } catch {}
+        return { content: [{ type: "text", text: JSON.stringify({ count: snapshot.length, events: snapshot, resources }) }] };
       }
       if (action === "stop") {
         const remaining = [...watchState.events];
         cleanupWatch();
+        setIdleSuppressed(false);
         return { content: [{ type: "text", text: JSON.stringify({ status: "stopped", captured: remaining.length, events: remaining }) }] };
       }
       return { content: [{ type: "text", text: JSON.stringify({ error: "Invalid action" }) }] };
@@ -542,7 +586,7 @@ const tools = {
     description: "Switch to a different browser tab by targetId.",
     schema: { targetId: z.string().describe("Target tab ID to switch to") },
     handler: async ({ targetId }) => {
-      const result = switchTab(targetId);
+      const result = await switchTab(targetId);
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     },
   },
@@ -587,10 +631,105 @@ const tools = {
     },
   },
 
+  // ═══════════════ ON-DEMAND CAPABILITIES ═══════════════
+  // Verbs ship, weight doesn't. Heavy backends (yt-dlp, reportlab) are NEVER
+  // bundled — probed at call time, installed only on explicit user consent.
+
+  browser_download: {
+    description: "Download media from a URL (video, audio, subtitles, thumbnail). Requires yt-dlp on the system — if missing, returns install instructions instead of failing silently. No silent installs, ever.",
+    schema: {
+      url: z.string().describe("Media URL"),
+      format: z.enum(["best", "audio", "video", "subtitles", "thumbnail"]).describe("What to download").optional(),
+      quality: z.enum(["best", "good", "worst"]).describe("Quality tier").optional(),
+    },
+    handler: async ({ url, format = "best", quality = "best" }) => {
+      // No shell metachars ever reach execSync — http(s) only.
+      if (!/^https?:\/\/[^\\s"';`$(){}|&<>]+$/i.test(url)) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "refused: URL must be http(s) without shell metacharacters" }) }] };
+      }
+      let hasYtDlp = false;
+      try {
+        execSync("yt-dlp --version", { stdio: "ignore", timeout: 5000 });
+        hasYtDlp = true;
+      } catch {}
+      if (!hasYtDlp) {
+        return { content: [{ type: "text", text: JSON.stringify({
+          needsInstall: true,
+          tool: "yt-dlp",
+          install: {
+            termux: "pkg install yt-dlp",
+            debian: "pip install yt-dlp",
+            macos: "brew install yt-dlp",
+          },
+          ask: "yt-dlp is not installed. Reply YES (agent: ask the human) to install it, or install manually and retry. Nothing was downloaded.",
+        }) }] };
+      }
+      const outDir = join(dirname(cfg.screenshotsDir), "bwb-downloads");
+      try { mkdirSync(outDir, { recursive: true }); } catch {}
+      const args = ["--no-playlist", "-P", outDir, "--print", "after_move:filepath"];
+      if (format === "audio") args.push("-x", "--audio-format", "mp3");
+      else if (format === "subtitles") args.push("--write-subs", "--skip-download");
+      else if (format === "thumbnail") args.push("--write-thumbnail", "--skip-download");
+      if (quality === "worst") args.push("-f", "worst");
+      else if (quality === "good") args.push("-f", "best[height<=720]");
+      args.push(url);
+      try {
+        const out = execSync(`yt-dlp ${args.map((a) => `"${a}"`).join(" ")}`, { encoding: "utf8", timeout: 600000, maxBuffer: 1024 * 1024 });
+        const file = out.trim().split("\n").pop();
+        return { content: [{ type: "text", text: JSON.stringify({ downloaded: file, format, quality }) }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "download failed", detail: String(err.message || err).slice(0, 500) }) }] };
+      }
+    },
+  },
+
+  browser_export: {
+    description: "Export findings/text to a file. md/txt/html always work (zero deps). docx/pdf/pptx need python libs — if missing, returns install instructions. No silent installs.",
+    schema: {
+      text: z.string().describe("Content to export (markdown accepted)"),
+      format: z.enum(["md", "txt", "html", "pdf", "docx", "pptx"]).describe("Output format").optional(),
+      output_path: z.string().describe("Where to write the file").optional(),
+      title: z.string().describe("Document title").optional(),
+    },
+    handler: async ({ text, format = "md", output_path, title = "bwb export" }) => {
+      const { writeFileSync: wfs } = await import("fs");
+      const dest = output_path || join(dirname(cfg.screenshotsDir), `bwb-export-${Date.now()}.${format === "txt" ? "txt" : format === "html" ? "html" : "md"}`);
+      if (["md", "txt"].includes(format)) {
+        try { wfs(dest, text, "utf8"); } catch (err) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: `write failed: ${err.message}` }) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ exported: dest, format }) }] };
+      }
+      if (format === "html") {
+        const esc = text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+        try { wfs(dest, `<!doctype html><html><head><meta charset="utf8"><title>${title}</title></head><body><pre>${esc}</pre></body></html>`, "utf8"); } catch (err) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: `write failed: ${err.message}` }) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ exported: dest, format }) }] };
+      }
+      // pdf/docx/pptx need python libs — probe, then consent-gate.
+      const need = { pdf: "reportlab", docx: "python-docx", pptx: "python-pptx" }[format];
+      let have = false;
+      try {
+        execSync(`python3 -c "import ${need.split("-").join("_")}"`, { stdio: "ignore", timeout: 10000 });
+        have = true;
+      } catch {}
+      if (!have) {
+        return { content: [{ type: "text", text: JSON.stringify({
+          needsInstall: true,
+          tool: need,
+          install: `pip install ${need}`,
+          ask: `${need} is not installed. Reply YES (agent: ask the human) to install it, or install manually and retry. Nothing was written. md/txt/html export works without it.`,
+        }) }] };
+      }
+      return { content: [{ type: "text", text: JSON.stringify({ ready: true, tool: need, note: "Backend present. Tell the agent to run the conversion explicitly — bwb never executes installs itself." }) }] };
+    },
+  },
+
   // ═══════════════ LIFECYCLE ═══════════════
 
   browser_status: {
-    description: "Get browser and page status including opened tabs and connection info.",
+    description: "Get browser and page status including opened tabs and connection info. v4: includes live resource readings (MCP + Chromium MB, budgets) so the agent sees pressure before Android does.",
     schema: {},
     handler: async () => {
       const status = { connected: false, port: cfg.port, actualPort: null, running: false, pid: null, tabs: [] };
@@ -610,6 +749,11 @@ const tools = {
           } catch { status.connected = false; }
         }
       }
+      try {
+        status.resources = sampleResources(browser?.pid, status.tabs.filter((t) => !t.hibernated).length);
+        status.resources.state = assess(status.resources);
+        status.profile = { lean: cfg.lean, nuclear: cfg.nuclear, idleMs: cfg.idleMs, tabMax: cfg.tabMax };
+      } catch {}
       return { content: [{ type: "text", text: JSON.stringify(status) }] };
     },
   },
@@ -628,8 +772,45 @@ const tools = {
 
 // ─── Register & Start ─────────────────────────────────────────────────────────
 
+// Single choke point for every tool call: poke the mayfly timer, then append
+// a ~100-byte resource footer. On critical pressure, shed load BEFORE
+// returning — hibernate oldest tabs, teardown at one tab — and say so.
 for (const [name, tool] of Object.entries(tools)) {
-  server.tool(name, tool.description, tool.schema, tool.handler);
+  const inner = tool.handler;
+  server.tool(name, tool.description, tool.schema, async (args) => {
+    let result;
+    try {
+      result = await inner(args);
+    } finally {
+      try { pokeActivity(); } catch {}
+    }
+    try {
+      const liveTabs = listTabs().filter((t) => !t.hibernated).length;
+      const sample = sampleResources(browser?.pid, liveTabs);
+      let note = "";
+      if (assess(sample) === "critical" && browser && !browserExited) {
+        // Evidence first: keep the peak numbers that triggered the shed.
+        const peak = `${sample.mcpMb}+${sample.chromiumMb ?? "?"}MB`;
+        // Shed oldest non-active tabs first; teardown at one tab. Journal keeps all.
+        const victims = listTabs().filter((t) => !t.active && !t.hibernated).map((t) => t.id);
+        for (const id of victims) {
+          await hibernateTab(id);
+          const after = sampleResources(browser?.pid, listTabs().filter((t) => !t.hibernated).length);
+          note = `shed tab ${id.slice(0, 8)} at peak ${peak}`;
+          Object.assign(sample, after);
+          if (assess(sample) !== "critical") break;
+        }
+        if (assess(sample) === "critical" && listTabs().filter((t) => !t.hibernated).length <= 1) {
+          try { await stopBrowser("oom-guard"); } catch {}
+          note += `${note ? "; " : ""}browser stopped at peak ${peak} (oom-guard) — journal saved, next call resurrects`;
+        }
+      }
+      if (result && Array.isArray(result.content)) {
+        result.content.push({ type: "text", text: resourceFooter(sample, note) });
+      }
+    } catch {}
+    return result;
+  });
 }
 
 await ensureDeps();