barebrowse 0.2.2 → 0.3.1

package/docs/{testing.md → 04-process/testing.md}

@@ -6,14 +6,14 @@
 node --test test/unit/*.test.js test/integration/*.test.js
 ```
 
-54 tests, 5 files, ~45s on a typical machine. No test framework -- uses Node's built-in `node:test` runner.
+64 tests, 6 files, ~60s on a typical machine. No test framework -- uses Node's built-in `node:test` runner.
 
 ## Test pyramid
 
 ```
           /  E2E  \         15 tests — real websites (Google, Wikipedia, GitHub, etc.)
          /----------\
-        / Integration \     11 tests — full browse/connect pipeline against example.com, HN
+        / Integration \     21 tests — browse/connect pipeline + CLI session lifecycle
        /----------------\
       /      Unit        \  28 tests — pruning, cookie extraction, CDP client, browser launch
      /--------------------\
@@ -98,6 +98,25 @@ Tests the full `browse()` and `connect()` pipeline end-to-end against real pages
 | 10 | connect() | supports multiple navigations in one session | Multiple goto() calls on same page |
 | 11 | connect() | snapshot accepts prune: false for raw output | snapshot(false) preserves full tree |
 
+### `test/integration/cli.test.js` -- 10 tests
+
+Tests the full CLI session lifecycle: daemon spawn, command dispatch over HTTP, and cleanup. Uses a temp directory so tests don't pollute the project.
+
+| # | Test | What it validates |
+|---|------|-------------------|
+| 1 | open starts a daemon and creates session.json | `barebrowse open about:blank` spawns daemon, writes session.json with port+pid |
+| 2 | status shows running session | `barebrowse status` reports pid, port, start time |
+| 3 | snapshot creates a .yml file | `barebrowse snapshot` writes .barebrowse/page-*.yml |
+| 4 | goto navigates and snapshot shows new page content | `barebrowse goto example.com` + snapshot contains "Example Domain" + refs |
+| 5 | click sends click command | `barebrowse click <ref>` returns "ok" |
+| 6 | eval executes JS and returns result | `barebrowse eval 1+1` returns "2" |
+| 7 | console-logs creates a .json file | After eval with console.log, `console-logs` writes JSON |
+| 8 | network-log creates a .json file | `network-log` writes JSON with request entries |
+| 9 | close shuts down the daemon | `barebrowse close` removes session.json, daemon exits |
+| 10 | status after close shows no session | `barebrowse status` exits non-zero when no session |
+
+Note: Tests run sequentially within the suite (each depends on the session opened in test 1). The `after()` hook ensures daemon cleanup even if tests fail.
+
 ---
 
 ## E2E tests (15 tests)

package/docs/README.md

@@ -0,0 +1,55 @@
+# barebrowse -- Documentation
+
+## Navigation
+
+### 00-context/ -- Why and what exists
+
+| File | What's in it |
+|------|-------------|
+| [vision.md](00-context/vision.md) | What barebrowse is, what it's not, the core insight, success criteria |
+| [assumptions.md](00-context/assumptions.md) | Hard constraints, assumptions, known limitations, risks |
+| [system-state.md](00-context/system-state.md) | Current architecture, full pipeline, module table, capabilities, tested sites |
+
+### 01-product/ -- What the product must do
+
+| File | What's in it |
+|------|-------------|
+| [prd.md](01-product/prd.md) | Product requirements, API design, three modes, pruning strategy, future features |
+
+### 02-features/ -- How features are designed
+
+*Feature-specific docs go here as the project grows.*
+
+### 03-logs/ -- What changed over time
+
+| File | What's in it |
+|------|-------------|
+| [decisions-log.md](03-logs/decisions-log.md) | Settled design decisions with rationale (don't re-debate these) |
+| [implementation-log.md](03-logs/implementation-log.md) | What changed per version (summary of CHANGELOG) |
+| [bug-log.md](03-logs/bug-log.md) | Bugs: symptom, root cause, fix, regression test |
+| [validation-log.md](03-logs/validation-log.md) | Test suite results, site validation matrix, token reduction measurements |
+| [insights.md](03-logs/insights.md) | Lessons learned, repos studied, technical patterns |
+
+### 04-process/ -- How to work with this system
+
+| File | What's in it |
+|------|-------------|
+| [dev-workflow.md](04-process/dev-workflow.md) | Dev rules, dependency hierarchy, running tests, environment setup |
+| [definition-of-done.md](04-process/definition-of-done.md) | Checklist: when is a feature/fix actually done |
+| [testing.md](04-process/testing.md) | Test pyramid, all 64 tests documented, writing new tests, CI strategy |
+
+### archive/ -- Historical docs
+
+| File | Why archived |
+|------|-------------|
+| [poc-plan.md](archive/poc-plan.md) | All 4 POC phases completed. Useful bits migrated to system-state.md and testing.md. |
+
+## Also at project root
+
+| File | Purpose |
+|------|---------|
+| `README.md` | Public-facing project overview |
+| `barebrowse.context.md` | LLM-consumable integration guide (full API, gotchas, wiring) |
+| `.claude/skills/barebrowse/SKILL.md` | CLI command reference + Claude Code skill definition |
+| `CHANGELOG.md` | Detailed version-by-version changelog |
+| `CLAUDE.md` | AI agent instructions for this project |

package/docs/archive/poc-plan.md

@@ -0,0 +1,230 @@
+# barebrowse — POC Plan
+
+**Date:** 2026-02-22
+**Goal:** Prove that an autonomous agent can get an authenticated, pruned ARIA snapshot of any web page via CDP — no Playwright, no bundled browser.
+
+---
+
+## Repo Structure
+
+```
+barebrowse/
+├── src/
+│   ├── index.js          # Public API: browse(), connect()
+│   ├── chromium.js        # Find/launch/connect to Chromium browsers
+│   ├── cdp.js             # Vanilla WebSocket CDP client
+│   ├── aria.js            # Accessibility.getFullAXTree → structured tree
+│   ├── auth.js            # Cookie extraction + CDP Network.setCookie injection
+│   ├── prune.js           # ARIA tree pruning (ported from mcprune)
+│   ├── interact.js        # Click, type, scroll via CDP Input domain
+│   ├── consent.js         # Auto-dismiss cookie consent dialogs
+│   └── stealth.js         # Anti-detection patches via Runtime.evaluate (Phase 4)
+├── test/
+│   ├── integration/
+│   │   ├── browse.test.js     # End-to-end: URL → pruned snapshot
+│   │   ├── auth.test.js       # Cookie injection → authenticated page
+│   │   └── interact.test.js   # Click/type on a live page
+│   └── unit/
+│       ├── cdp.test.js        # CDP client message handling
+│       ├── aria.test.js       # ARIA tree formatting
+│       └── prune.test.js      # Pruning logic on sample trees
+├── docs/
+│   ├── prd.md             # Product requirements (comprehensive)
+│   └── poc-plan.md        # This file
+├── package.json
+└── CLAUDE.md
+```
+
+**No build step.** Vanilla JS, ES modules, runs directly with Node.js >= 22.
+
+---
+
+## Phases
+
+### Phase 1 — CDP + ARIA Foundation
+
+**Prove:** Get an ARIA tree from any page via CDP, no Playwright.
+
+**Files:**
+- `src/chromium.js` — Find installed Chromium browsers on the system (Chrome, Chromium, Brave, Edge). Launch headless with `--headless=new --remote-debugging-port=<port>`. Parse CDP WebSocket URL from stderr output.
+- `src/cdp.js` — Vanilla WebSocket client that speaks CDP. Send JSON commands, receive responses and events. Handle command IDs, promises, event subscriptions. ~100 lines.
+- `src/aria.js` — Call `Accessibility.getFullAXTree` via CDP. Transform the raw CDP response (flat array of AXNodes with parentId references) into a nested tree structure. Format as readable output.
+- `src/index.js` — Wire chromium → cdp → aria into `browse(url)` function. Minimal, just the pipeline.
+
+**Test:**
+```bash
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://example.com'))"
+```
+
+**DoD:**
+- [x] `chromium.js` finds and launches at least one Chromium browser on Fedora Linux
+- [x] `cdp.js` connects via WebSocket, sends commands, receives responses
+- [x] `aria.js` returns a structured ARIA tree for any public page
+- [x] `browse(url)` works end-to-end with zero external dependencies
+- [x] Headless Chrome process is cleaned up on close
+
+### Phase 2 — Auth + Prune
+
+**Prove:** Authenticated, pruned ARIA snapshot of a Cloudflare-protected page.
+
+**Files:**
+- `src/auth.js` — Extract cookies from user's browser profile (use sweet-cookie or implement minimal extraction from Chrome's Cookies SQLite DB + Linux keyring decryption via `secret-tool`). Inject via CDP `Network.setCookie` before navigation.
+- `src/prune.js` — Port mcprune's pruning logic as a pure function. Input: raw ARIA tree. Output: pruned ARIA tree. Role-based: keep landmarks + interactive elements, drop noise/structural wrappers.
+- Update `src/index.js` — Add cookie injection and pruning to the `browse()` pipeline.
+
+**Test:**
+```bash
+# Should return authenticated content, not a login wall or CF challenge
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://some-cf-protected-site.com'))"
+```
+
+**DoD:**
+- [x] `auth.js` extracts cookies from Firefox profile on Linux (also supports Chromium when installed)
+- [x] Cookies injected via CDP before navigation
+- [ ] CF-protected page returns real content, not challenge page (needs active session to test)
+- [x] `prune.js` reduces ARIA tree by 47%+ on HN (minimal site — heavier sites will see 70%+)
+- [x] Pruned output preserves all interactive elements and landmarks
+- [x] `browse(url)` returns pruned, authenticated snapshot by default
+
+### Phase 3 — Headed Mode + Interaction
+
+**Prove:** Connect to user's running browser and interact with a logged-in page.
+
+**Files:**
+- Update `src/chromium.js` — Add `connect()` mode: connect to an already-running browser's debug port instead of launching a new one. Detect running browsers with debug ports.
+- `src/interact.js` — Click (`Input.dispatchMouseEvent`), type (`Input.dispatchKeyEvent`), scroll. Resolve ARIA node IDs to DOM coordinates for click targets.
+- Update `src/index.js` — Add `connect()` export for long-lived sessions. Add `mode: 'headed'` option.
+
+**Prerequisite:** User must launch their browser with `--remote-debugging-port=9222` flag.
+
+**Test:**
+```bash
+# User has Chrome open with debug port, logged into GitHub
+node -e "
+  import { connect } from './src/index.js';
+  const page = await connect({ mode: 'headed' });
+  await page.goto('https://github.com/notifications');
+  console.log(await page.snapshot());
+"
+```
+
+**DoD:**
+- [x] `connect()` attaches to a running Chromium browser via CDP
+- [x] Same ARIA + prune pipeline works on headed browser
+- [x] `click()` and `type()` send real input events via CDP
+- [x] `press()` sends special keys (Enter, Tab, Escape, arrows) — triggers form submit
+- [x] `scrollIntoView` before click ensures off-screen elements are reachable
+- [x] `type({ clear: true })` replaces pre-filled input content
+- [x] `waitForNavigation()` waits for page load after link clicks
+- [x] Interactions tested against real sites: Wikipedia, GitHub, Google, Hacker News, DuckDuckGo, YouTube
+- [x] Browser stays open after barebrowse disconnects
+- [x] Cookie injection via `page.injectCookies()` for headed mode (Firefox → Chromium)
+- [x] Permission prompts suppressed via launch flags + CDP `Browser.setPermission`
+- [x] Cookie consent dialogs auto-dismissed across 16+ sites in 7 languages
+- [x] YouTube end-to-end: Firefox cookies → search → click → video playback in headed mode
+
+### Phase 4 — Hybrid + bareagent Integration
+
+**Prove:** Agent autonomously browses the web using barebrowse tools.
+
+**Files:**
+- Update `src/chromium.js` — Add `mode: 'hybrid'`. Try headless first. If navigation returns a CF challenge or 403, automatically retry in headed mode.
+- `src/stealth.js` — Basic anti-detection: patch `navigator.webdriver`, `navigator.plugins`, `window.chrome`. Applied via `Runtime.evaluate` on new page.
+- Update `src/index.js` — Final API surface: `browse()`, `connect()`.
+
+**Test:**
+```js
+import { Loop } from 'bare-agent';
+import { browse } from './src/index.js';
+
+const tools = [
+  { name: 'browse', execute: ({ url }) => browse(url) },
+];
+
+const loop = new Loop({ provider });
+await loop.run([
+  { role: 'user', content: 'Go to hacker news and tell me the top 3 stories' }
+], tools);
+```
+
+**DoD:**
+- [ ] Hybrid mode automatically falls back when headless is blocked
+- [ ] Stealth patches reduce headless detection on common sites
+- [ ] bareagent can use `browse()` as a tool in its think/act/observe loop
+- [ ] Agent successfully completes a multi-page research task autonomously
+
+---
+
+## Definition of Done — Full POC
+
+The POC is complete when ALL of these are true:
+
+1. **`browse(url)` works end-to-end** — URL in, pruned ARIA snapshot out, authenticated as the user
+2. **Zero heavy deps** — no Playwright, no Puppeteer. Only deps: `ws` (WebSocket client, if Node's built-in isn't sufficient) and optionally `sweet-cookie`
+3. **Three modes work** — headless (default), headed (connect to running browser), hybrid (auto-fallback)
+4. **Works on Fedora Linux** — finds Chrome/Chromium/Brave, launches headless, connects headed
+5. **Token-efficient output** — pruned ARIA tree is 70%+ smaller than raw tree
+6. **Clean process management** — headless browser spawned and killed cleanly, no orphan processes
+7. **Under 1,000 lines total** for core src/ (excluding tests)
+8. **Documented** — PRD captures all decisions, this file captures all phases
+
+## What the POC is NOT
+
+- Not production-ready. No error recovery, no retry logic, no edge case handling beyond happy path.
+- Not cross-platform tested. Linux first (Fedora). macOS/Windows later.
+- Not an MCP server. That's a future wrapper.
+- Not a published npm package. Local development only.
+
+---
+
+## Running Tests
+
+```bash
+# All tests (47+ tests)
+node --test test/unit/*.test.js test/integration/*.test.js
+
+# Unit tests only (fast, no network)
+node --test test/unit/prune.test.js    # 16 tests — pruning logic
+node --test test/unit/auth.test.js     # 7 tests — cookie extraction (2 fail when Chromium locked)
+node --test test/unit/cdp.test.js      # 5 tests — CDP client + browser launch
+
+# Integration tests (needs network + Chromium)
+node --test test/integration/browse.test.js    # 11 tests — end-to-end pipeline
+node --test test/integration/interact.test.js  # 15 tests — interactions on real sites
+
+# Quick smoke test
+node -e "import { browse } from './src/index.js'; console.log(await browse('https://example.com'))"
+
+# Headed mode demos (requires: chromium-browser --remote-debugging-port=9222)
+node examples/headed-demo.js    # Wikipedia → DuckDuckGo search
+node examples/yt-demo.js        # YouTube: Firefox cookies → search → play video
+```
+
+---
+
+## Repos Studied — What We Borrowed vs Built
+
+| steipete repo | What we studied | What we used | Why not more |
+|---|---|---|---|
+| **sweet-cookie** | Cookie extraction (SQLite + keyring) | **Concept only** — wrote `auth.js` ourselves | Not on npm (different package). Our version is simpler, tailored, vanilla JS |
+| **sweetlink** | CDP dual-channel, selector discovery, daemon | **CDP-direct concept only** | Daemon + WebSocket bridge + in-page runtime = bloat. CDP direct is 100 lines vs ~2,000 |
+| **canvas** | Stealth/anti-detection patterns | **Noted for Phase 4** `stealth.js` | Not needed yet — headless + real cookies handles most cases |
+| **mcprune (own)** | ARIA pruning pipeline | **Full port** — `prune.js` (472 lines) | Proven code, adapted node format from Playwright YAML to CDP tree objects |
+
+### What to explore in later phases
+
+- **Selector discovery** (sweetlink) — crawl ARIA tree, score interactive elements, rank action targets. Phase 3/4.
+- **Stealth patches** (canvas) — `navigator.webdriver`, plugins, chrome object spoofing. Phase 4.
+- **In-page JS execution** (sweetlink) — `Runtime.evaluate` for complex interactions. Phase 3.
+- **Screenshot + visual grounding** — `Page.captureScreenshot` for multimodal agents. Post-POC.
+
+---
+
+## Dev Rules (from AGENT_RULES.md)
+
+- **Vanilla JS only.** No TypeScript, no build step, no transpilation.
+- **Dependency hierarchy:** vanilla → stdlib → external. Write it yourself if <50 lines.
+- **Simple > clever.** Readable code a junior can follow.
+- **POC first.** Validate logic before designing. Never ship the POC — rewrite it.
+- **Test behavior, not implementation.** Integration tests over unit tests.
+- **No speculative code.** Every line must have a purpose.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barebrowse",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
   "type": "module",
   "main": "src/index.js",

package/src/aria.js

@@ -20,7 +20,7 @@ export function formatTree(node, depth = 0) {
 
   // Skip ignored nodes but still process their children
   if (node.ignored) {
-    return node.children.map((c) => formatTree(c, depth)).join('');
+    return node.children.map((c) => formatTree(c, depth)).filter(Boolean).join('\n');
   }
 
   // Skip low-level rendering nodes that are noise for agents

package/src/daemon.js

@@ -0,0 +1,321 @@
+/**
+ * daemon.js -- Background HTTP server holding a connect() session.
+ *
+ * startDaemon()  — spawn a detached child process running the daemon
+ * runDaemon()    — the actual HTTP server (called via --daemon-internal)
+ */
+
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { writeFileSync, mkdirSync, existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { connect } from './index.js';
+
+const SESSION_FILE = 'session.json';
+
+/**
+ * Spawn a detached child process that runs the daemon.
+ * Parent polls for session.json, then exits.
+ */
+export async function startDaemon(opts, outputDir, initialUrl) {
+  const absDir = resolve(outputDir);
+  mkdirSync(absDir, { recursive: true });
+
+  // Clean stale session
+  const sessionPath = join(absDir, SESSION_FILE);
+  if (existsSync(sessionPath)) unlinkSync(sessionPath);
+
+  // Build child args
+  const args = [join(import.meta.dirname, '..', 'cli.js'), '--daemon-internal'];
+  args.push('--output-dir', absDir);
+  if (initialUrl) args.push('--url', initialUrl);
+  if (opts.mode) args.push('--mode', opts.mode);
+  if (opts.port) args.push('--port', String(opts.port));
+  if (opts.cookies === false) args.push('--no-cookies');
+  if (opts.browser) args.push('--browser', opts.browser);
+  if (opts.timeout) args.push('--timeout', String(opts.timeout));
+  if (opts.pruneMode) args.push('--prune-mode', opts.pruneMode);
+  if (opts.consent === false) args.push('--no-consent');
+
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env },
+  });
+  child.unref();
+
+  // Poll for session.json (50ms interval, 15s timeout)
+  const deadline = Date.now() + 15000;
+  while (Date.now() < deadline) {
+    if (existsSync(sessionPath)) {
+      try {
+        const data = JSON.parse(readFileSync(sessionPath, 'utf8'));
+        if (data.port && data.pid) return data;
+      } catch { /* partial write, retry */ }
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error('Daemon failed to start within 15s');
+}
+
+/**
+ * Run the daemon HTTP server. Called by cli.js --daemon-internal.
+ * Holds a connect() session and serves commands over HTTP.
+ */
+export async function runDaemon(opts, outputDir, initialUrl) {
+  const absDir = resolve(outputDir);
+  mkdirSync(absDir, { recursive: true });
+
+  // Connect to browser
+  const page = await connect({
+    mode: opts.mode || 'headless',
+    port: opts.port ? Number(opts.port) : undefined,
+    consent: opts.consent,
+  });
+
+  // Console log capture
+  const consoleLogs = [];
+  await page.cdp.send('Runtime.enable');
+  page.cdp.on('Runtime.consoleAPICalled', (params) => {
+    consoleLogs.push({
+      type: params.type,
+      timestamp: new Date().toISOString(),
+      args: params.args.map((a) => a.value ?? a.description ?? a.type),
+    });
+  });
+
+  // Network log capture (Network.enable already called by connect)
+  const networkLogs = [];
+  const pendingRequests = new Map();
+
+  page.cdp.on('Network.requestWillBeSent', (params) => {
+    pendingRequests.set(params.requestId, {
+      url: params.request.url,
+      method: params.request.method,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  page.cdp.on('Network.responseReceived', (params) => {
+    const req = pendingRequests.get(params.requestId);
+    if (req) {
+      networkLogs.push({
+        ...req,
+        status: params.response.status,
+        statusText: params.response.statusText,
+        mimeType: params.response.mimeType,
+      });
+      pendingRequests.delete(params.requestId);
+    }
+  });
+
+  page.cdp.on('Network.loadingFailed', (params) => {
+    const req = pendingRequests.get(params.requestId);
+    if (req) {
+      networkLogs.push({
+        ...req,
+        status: 0,
+        error: params.errorText,
+      });
+      pendingRequests.delete(params.requestId);
+    }
+  });
+
+  // Navigate to initial URL if provided
+  if (initialUrl) {
+    if (opts.cookies !== false) {
+      try { await page.injectCookies(initialUrl, { browser: opts.browser }); } catch { /* no cookies */ }
+    }
+    await page.goto(initialUrl, opts.timeout ? Number(opts.timeout) : 30000);
+  }
+
+  // Default prune mode
+  const defaultPruneMode = opts.pruneMode || 'act';
+
+  // Command handlers
+  const handlers = {
+    async goto({ url, timeout }) {
+      await page.goto(url, timeout || 30000);
+      return { ok: true };
+    },
+
+    async snapshot({ mode }) {
+      const pruneMode = mode || defaultPruneMode;
+      const text = await page.snapshot({ mode: pruneMode });
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(absDir, `page-${ts}.yml`);
+      writeFileSync(file, text);
+      return { ok: true, file };
+    },
+
+    async screenshot({ format }) {
+      const data = await page.screenshot({ format: format || 'png' });
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const ext = format || 'png';
+      const file = join(absDir, `screenshot-${ts}.${ext}`);
+      writeFileSync(file, Buffer.from(data, 'base64'));
+      return { ok: true, file };
+    },
+
+    async click({ ref }) {
+      await page.click(String(ref));
+      return { ok: true };
+    },
+
+    async type({ ref, text, clear }) {
+      await page.type(String(ref), text, clear ? { clear: true } : undefined);
+      return { ok: true };
+    },
+
+    async fill({ ref, text }) {
+      await page.type(String(ref), text, { clear: true });
+      return { ok: true };
+    },
+
+    async press({ key }) {
+      await page.press(key);
+      return { ok: true };
+    },
+
+    async scroll({ deltaY }) {
+      await page.scroll(Number(deltaY));
+      return { ok: true };
+    },
+
+    async hover({ ref }) {
+      await page.hover(String(ref));
+      return { ok: true };
+    },
+
+    async select({ ref, value }) {
+      await page.select(String(ref), value);
+      return { ok: true };
+    },
+
+    async eval({ expression }) {
+      const result = await page.cdp.send('Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+      });
+      if (result.exceptionDetails) {
+        return { ok: false, error: result.exceptionDetails.text || 'eval error' };
+      }
+      return { ok: true, value: result.result.value };
+    },
+
+    async 'wait-idle'({ timeout }) {
+      await page.waitForNetworkIdle({ timeout: timeout || 30000 });
+      return { ok: true };
+    },
+
+    async 'wait-nav'({ timeout }) {
+      await page.waitForNavigation(timeout || 30000);
+      return { ok: true };
+    },
+
+    async 'console-logs'({ level, clear }) {
+      let logs = consoleLogs;
+      if (level) logs = logs.filter((l) => l.type === level);
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(absDir, `console-${ts}.json`);
+      writeFileSync(file, JSON.stringify(logs, null, 2));
+      if (clear) consoleLogs.length = 0;
+      return { ok: true, file, count: logs.length };
+    },
+
+    async 'network-log'({ failed }) {
+      let logs = networkLogs;
+      if (failed) logs = logs.filter((l) => l.status === 0 || l.status >= 400);
+      const ts = new Date().toISOString().replace(/[:.]/g, '-');
+      const file = join(absDir, `network-${ts}.json`);
+      writeFileSync(file, JSON.stringify(logs, null, 2));
+      return { ok: true, file, count: logs.length };
+    },
+
+    async close() {
+      await page.close();
+      // Clean up session file
+      const sessionPath = join(absDir, SESSION_FILE);
+      if (existsSync(sessionPath)) unlinkSync(sessionPath);
+      // Respond before exiting
+      return { ok: true };
+    },
+
+    async status() {
+      return { ok: true, pid: process.pid, uptime: process.uptime() };
+    },
+  };
+
+  // Start HTTP server on random port
+  const server = createServer(async (req, res) => {
+    if (req.method === 'GET' && req.url === '/status') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, pid: process.pid }));
+      return;
+    }
+
+    if (req.method !== 'POST' || req.url !== '/command') {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+
+    let body = '';
+    for await (const chunk of req) body += chunk;
+
+    let parsed;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'Invalid JSON' }));
+      return;
+    }
+
+    const { command, args } = parsed;
+    const handler = handlers[command];
+    if (!handler) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: `Unknown command: ${command}` }));
+      return;
+    }
+
+    try {
+      const result = await handler(args || {});
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(result));
+
+      // Exit after close command
+      if (command === 'close') {
+        server.close();
+        process.exit(0);
+      }
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: err.message }));
+    }
+  });
+
+  await new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => resolve());
+  });
+
+  const port = server.address().port;
+
+  // Write session.json so parent/clients can find us
+  const sessionPath = join(absDir, SESSION_FILE);
+  writeFileSync(sessionPath, JSON.stringify({
+    port,
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+  }));
+
+  // Handle SIGTERM gracefully
+  process.on('SIGTERM', async () => {
+    try { await page.close(); } catch { /* already closed */ }
+    if (existsSync(sessionPath)) unlinkSync(sessionPath);
+    server.close();
+    process.exit(0);
+  });
+}