prism-mcp-server 20.3.0 → 20.3.2

package/README.md

@@ -61,6 +61,75 @@ features.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.3.2
+
+### Web Scholar: SSRF Hardening
+
+Security release. Web Scholar scrapes article URLs that come from
+search-engine output, so the target is attacker-influenceable through SEO
+poisoning — and because what it scrapes is written into the memory corpus and
+passed to the configured LLM, a redirection to a local address meant reading an
+internal service *and* sending the result onward.
+
+The host guard matched string prefixes instead of parsing the address, and six
+spellings of a local address got through: `[::1]` (`URL.hostname` keeps the
+brackets), `127.0.0.2` (only `.1` was enumerated, not all of `127.0.0.0/8`),
+`0.0.0.0`, `[::ffff:127.0.0.1]`, `localhost.` (a trailing dot defeated every
+suffix check at once), and `[64:ff9b::7f00:1]` (NAT64 embeds IPv4 in its low
+bits). Host classification now parses addresses and also covers CGNAT,
+benchmarking, multicast, reserved, and IPv6 unique-local and link-local ranges.
+
+DNS rebinding is closed too. Every check read the URL string, so a hostname the
+attacker controls passed all of them and could still resolve to `127.0.0.1`.
+Targets are now resolved first, every returned address is validated, and the
+connection is pinned to those addresses so the name is never resolved a second
+time — which also shuts the window between the check and the connect.
+
+Scrape failures no longer vanish into a bare `catch {}`, a run is bounded by
+`PRISM_SCHOLAR_SCRAPE_BUDGET_MS` (default 60s) instead of stalling on a raised
+article count, and responses are capped at 8 MiB.
+
+This is reachable only when scholar actually runs — `scholar_research`, or the
+background loop under `PRISM_SCHOLAR_ENABLED=true` — and when the attacker also
+controls DNS or a search result. Upgrade if you use Web Scholar.
+
+---
+
+## What's New in v20.3.1
+
+### Prism Browser Reports Real Failures
+
+`prism browser` could not fail a test. `eval 1 === 2` returned `status: ok`
+with exit code 0, a page serving HTTP 500 reported `status: ok`, and console
+errors and uncaught page exceptions were discarded entirely. This release adds
+assertions — `assert-text`, `assert-visible`, `assert-count`, `assert-url`,
+`assert-title`, `assert-eval`, `assert-no-page-errors` — that return
+`status: failed` and a non-zero exit. `open` now reports `http_status` and
+fails on 400 or higher, screenshots are validated rather than assumed, and
+`eval` returns native JSON with its type instead of a Python `repr`.
+
+The fingerprint layer had never been applied: a wrong keyword argument made
+the stealth library throw on every launch — 1,139 failures and 0 successes
+since April — while the runner reported it as active. It is fixed, and a layer
+that cannot be applied now fails loudly. The headless build no longer
+advertises itself through `navigator.userAgentData` or the `Sec-CH-UA` header,
+and a patch that corrupted `Object.getOwnPropertyDescriptor` on every page
+under test has been removed. These remain best-effort test aids, not a
+guarantee against bot detection.
+
+`--local-only` now actually isolates: WebSocket, EventSource, WebRTC and
+`sendBeacon` egress bypass request routing and were never blocked, and service
+workers were allowed through. `--cleanup` was a no-op in the two modes agents
+use. Site isolation, phishing detection and popup blocking are no longer
+disabled by default, since these profiles hold live authenticated cookies.
+
+New for test runs: `--ephemeral-profile` and `--storage-state` for hermetic
+authenticated flows, `pages`/`switch-page` so OAuth popups are reachable,
+`--fail-fast`, `--fast`, `--trace`/`--video`/`--har`, and
+`profiles --prune-older-than` for profile maintenance.
+
+---
+
 ## What's New in v20.2.7
 
 ### Session Saves Survive Agent Restarts
@@ -81,12 +150,12 @@ to the patched 8.5.23 release.
 
 ### Hybrid Memory Search (Portal Tier)
 
-`session_search_memory` on Synalux-backed installs now fuses semantic
-similarity with exact-term lexical matching (weighted reciprocal-rank
-fusion). On blind probes against a real 8.5k-entry corpus this lifted
-top-1 retrieval from 45% (semantic alone) to 59%; exact identifiers such
-as TPNs, function names and error strings now rescue queries that
-embeddings blur. Results say how they were found — `hybrid retrieval`
+`session_search_memory` on the portal tier (Synalux-backed installs) now
+fuses semantic similarity with exact-term lexical matching via weighted
+reciprocal-rank fusion. Measured on blind probes against a real
+8.5k-entry corpus: fused retrieval was **never worse** than semantic
+alone at top-5, and exact identifiers — TPNs, function names, error
+strings — now rescue queries that embedding similarity blurs. Results say how they were found — `hybrid retrieval`
 headers, per-hit `sem#/lex#` arms — and a lexical-only rescue is labelled
 `exact-term match` instead of pretending to a similarity score. Local
 SQLite installs keep pure vector search; hybrid needs the portal's

package/dist/config.js

@@ -202,6 +202,10 @@ if (PRISM_SCHOLAR_ENABLED && !FIRECRAWL_API_KEY) {
 export const PRISM_SCHOLAR_INTERVAL_MS = parseInt(process.env.PRISM_SCHOLAR_INTERVAL_MS || "0", 10 // Default manual-only
 );
 export const PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN = parseInt(process.env.PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN || "3", 10);
+// Wall-clock ceiling for a run's scrape loop. Scrapes are sequential with a
+// 15s per-fetch timeout, so without this a raised article count turns into a
+// multi-minute stall.
+export const PRISM_SCHOLAR_SCRAPE_BUDGET_MS = parseInt(process.env.PRISM_SCHOLAR_SCRAPE_BUDGET_MS || "60000", 10);
 export const PRISM_SCHOLAR_TOPICS = (process.env.PRISM_SCHOLAR_TOPICS || "ai,agents")
     .split(",")
     .map(t => t.trim());

package/dist/scholar/freeSearch.js

@@ -2,6 +2,12 @@ import * as cheerio from 'cheerio';
 import { JSDOM } from 'jsdom';
 import { Readability } from '@mozilla/readability';
 import TurndownService from 'turndown';
+import { lookup as dnsLookupCb } from 'node:dns';
+import http from 'node:http';
+import https from 'node:https';
+import net from 'node:net';
+import { promisify } from 'node:util';
+const dnsLookup = promisify(dnsLookupCb);
 /**
  * Searches Yahoo Web Search and parses the HTML results using Cheerio.
  * Yahoo provides a reliable HTML fallback that does not block basic automated browser requests.
@@ -42,47 +48,244 @@ export async function searchYahooFree(query, limit = 5) {
     });
     return results;
 }
+function classifyIPv4(octets) {
+    const [a, b] = octets;
+    if (a === 127)
+        return 'loopback'; // 127.0.0.0/8 — not just 127.0.0.1
+    if (a === 0)
+        return 'loopback'; // 0.0.0.0/8 routes to the local host
+    if (a === 10)
+        return 'private'; // RFC1918
+    if (a === 172 && b >= 16 && b <= 31)
+        return 'private';
+    if (a === 192 && b === 168)
+        return 'private';
+    if (a === 169 && b === 254)
+        return 'private'; // link-local + cloud metadata
+    if (a === 100 && b >= 64 && b <= 127)
+        return 'private'; // CGNAT
+    if (a === 192 && b === 0)
+        return 'private'; // IETF protocol assignments
+    if (a === 198 && (b === 18 || b === 19))
+        return 'private'; // benchmarking
+    if (a >= 224)
+        return 'private'; // multicast + reserved
+    return 'public';
+}
+function parseIPv4(host) {
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return null;
+    const octets = [];
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part))
+            return null;
+        const value = Number(part);
+        if (value > 255)
+            return null;
+        octets.push(value);
+    }
+    return octets;
+}
 /**
- * Fetches an article's HTML, extracts clean content via Readability,
- * and converts it to Markdown using Turndown.
+ * Classify a URL's host.
+ *
+ * Exported so the bypass table can be asserted directly. String-prefix checks
+ * are not sufficient here: `URL.hostname` keeps the brackets on IPv6 literals,
+ * 127.0.0.0/8 is far wider than 127.0.0.1, and 0.0.0.0 and IPv4-mapped IPv6
+ * both reach the local host.
  */
-export async function scrapeArticleLocal(url) {
-    // SSRF protection: reject private/internal URLs.
-    // Set PRISM_DEV_MODE=1 to allow loopback/private hosts during local dev
-    // (testing against a local docs server, internal wiki, etc.). The flag
-    // is intentionally OFF in production deploys.
-    const devMode = process.env.PRISM_DEV_MODE === '1' || process.env.NODE_ENV === 'development';
+export function classifyScrapeHost(rawHost) {
+    // URL.hostname returns IPv6 literals bracketed — strip the brackets. Node
+    // keeps a trailing '.' on named hosts (localhost. still resolves to
+    // 127.0.0.1), and that dot otherwise defeats every suffix check below.
+    const host = rawHost.toLowerCase()
+        .replace(/^\[|\]$/g, '')
+        .replace(/\.+$/, '');
+    if (host === 'localhost' || host.endsWith('.localhost'))
+        return 'loopback';
+    if (host.endsWith('.internal') || host.endsWith('.local'))
+        return 'private';
+    const ipv4 = parseIPv4(host);
+    if (ipv4)
+        return classifyIPv4(ipv4);
+    if (host.includes(':')) {
+        if (host === '::1')
+            return 'loopback';
+        if (host === '::')
+            return 'loopback';
+        // Prefixes that carry an IPv4 address in their low 32 bits. Node
+        // rewrites ::ffff:127.0.0.1 to ::ffff:7f00:1, so both the dotted and
+        // hex-pair spellings have to decode.
+        const embedding = /^(?:::ffff|64:ff9b(?::1)?::?)[:]?(.+)$/.exec(host);
+        if (embedding) {
+            const suffix = embedding[1];
+            const dotted = parseIPv4(suffix);
+            if (dotted)
+                return classifyIPv4(dotted);
+            const hexPair = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(suffix);
+            if (hexPair) {
+                const high = parseInt(hexPair[1], 16);
+                const low = parseInt(hexPair[2], 16);
+                return classifyIPv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+            }
+            // Reserved translation prefix with an undecodable tail — not public.
+            return 'private';
+        }
+        if (/^64:ff9b:/.test(host))
+            return 'private'; // NAT64 (RFC 6052/8215)
+        if (/^f[cd][0-9a-f]{2}:/.test(host))
+            return 'private'; // fc00::/7 unique-local
+        if (/^fe[89ab][0-9a-f]:/.test(host))
+            return 'private'; // fe80::/10 link-local
+        return 'public';
+    }
+    return 'public';
+}
+/**
+ * Reject scrape targets that point at the local host or an internal network.
+ *
+ * The URL reaching here comes from search-engine output, so it is
+ * attacker-influenceable via SEO poisoning. A successful fetch would be
+ * persisted into the memory corpus, so this fails closed.
+ */
+export function assertSafeScrapeTarget(url, devMode) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('Invalid URL: could not be parsed');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error(`Invalid URL: protocol ${parsed.protocol} is not allowed`);
+    }
+    const hostClass = classifyScrapeHost(parsed.hostname);
+    if (hostClass === 'private') {
+        // Never allowed, even in dev mode: on a shared LAN these can reach
+        // other machines, and 169.254.169.254 is cloud metadata.
+        throw new Error('Invalid URL: private network URLs not allowed');
+    }
+    if (hostClass === 'loopback' && !devMode) {
+        throw new Error('Invalid URL: loopback URLs not allowed in production (set PRISM_DEV_MODE=1 to allow)');
+    }
+}
+/** Max article HTML accepted, so a hostile endpoint cannot stream us to death. */
+const MAX_ARTICLE_BYTES = 8 * 1024 * 1024;
+/**
+ * Resolve a hostname and validate every address it answers with.
+ *
+ * The string checks above only see the hostname, so a name the attacker
+ * controls can pass them and still resolve to 127.0.0.1 (DNS rebinding).
+ * Returns the address to connect to, which the caller pins so the name is
+ * never resolved a second time.
+ */
+export async function resolveAndValidateHost(hostname, devMode) {
+    const bracketless = hostname.replace(/^\[|\]$/g, '');
+    // A literal address needs no lookup; assertSafeScrapeTarget already ruled on it.
+    if (net.isIP(bracketless) !== 0) {
+        return [{ address: bracketless, family: net.isIP(bracketless) }];
+    }
+    let resolved;
     try {
-        const parsed = new URL(url);
-        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
-            throw new Error('Invalid protocol');
-        const host = parsed.hostname.toLowerCase();
-        const isLoopback = host === 'localhost' || host === '127.0.0.1' || host === '::1';
-        const isPrivate = host.startsWith('10.') || host.startsWith('192.168.') || host.startsWith('169.254.') ||
-            /^172\.(1[6-9]|2\d|3[01])\./.test(host) || host.endsWith('.internal') || host.endsWith('.local');
-        if (isLoopback && !devMode) {
-            throw new Error('Loopback URLs not allowed in production (set PRISM_DEV_MODE=1 to allow)');
+        resolved = await dnsLookup(hostname, { all: true, verbatim: true });
+    }
+    catch (err) {
+        throw new Error(`Invalid URL: could not resolve ${hostname}`);
+    }
+    if (resolved.length === 0) {
+        throw new Error(`Invalid URL: ${hostname} resolved to no addresses`);
+    }
+    // Reject if ANY answer is non-public. A name that resolves to both a
+    // public and a private address is the rebinding shape itself, so picking
+    // the "good" one would just make the attack racy instead of blocked.
+    for (const entry of resolved) {
+        const hostClass = classifyScrapeHost(entry.address);
+        if (hostClass === 'private') {
+            throw new Error(`Invalid URL: ${hostname} resolves to a private address (${entry.address})`);
         }
-        if (isPrivate) {
-            // Private RFC1918 ranges are never allowed — even in dev mode they
-            // can cross into other tenants' machines on a shared LAN.
-            throw new Error('Private network URLs not allowed');
+        if (hostClass === 'loopback' && !devMode) {
+            throw new Error(`Invalid URL: ${hostname} resolves to a loopback address (${entry.address})`);
         }
     }
-    catch (e) {
-        throw new Error(`Invalid URL: ${e instanceof Error ? e.message : 'unknown'}`);
-    }
-    const response = await fetch(url, {
-        headers: {
-            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
-        },
-        redirect: 'error',
-        signal: AbortSignal.timeout(15_000),
+    // Every answer is validated, so returning all of them keeps Node's
+    // dual-stack fallback working. Pinning only the first would fail whenever
+    // a host's leading AAAA is unreachable, which plain fetch handles.
+    return resolved;
+}
+/**
+ * GET an article over a connection pinned to a pre-validated address.
+ *
+ * Node's fetch would resolve the name again inside the request, which
+ * reopens the rebinding window between our check and the connection
+ * (TOCTOU). Supplying `lookup` guarantees the socket goes to the address we
+ * validated, while the URL still supplies the Host header and TLS SNI.
+ */
+function fetchPinned(url, addresses) {
+    return new Promise((resolve, reject) => {
+        const transport = url.protocol === 'https:' ? https : http;
+        const req = transport.request(url, {
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+            },
+            // Node calls this in two shapes: with { all: true } it wants an
+            // array of { address, family } (autoSelectFamily, the default
+            // since Node 20), otherwise the (err, address, family) form.
+            // Answering the wrong one yields "Invalid IP address: undefined".
+            lookup: (_hostname, options, callback) => {
+                if (options && options.all) {
+                    callback(null, addresses);
+                }
+                else {
+                    callback(null, addresses[0].address, addresses[0].family);
+                }
+            },
+        }, (res) => {
+            const status = res.statusCode ?? 0;
+            if (status >= 300 && status < 400) {
+                // Matches the previous redirect: 'error' behaviour — a
+                // redirect is a second target that was never validated.
+                res.destroy();
+                reject(new Error(`Failed to fetch article HTML: refusing redirect (${status})`));
+                return;
+            }
+            if (status < 200 || status >= 300) {
+                res.destroy();
+                reject(new Error(`Failed to fetch article HTML: ${status} ${res.statusMessage ?? ''}`.trim()));
+                return;
+            }
+            let size = 0;
+            const chunks = [];
+            res.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > MAX_ARTICLE_BYTES) {
+                    res.destroy();
+                    reject(new Error(`Failed to fetch article HTML: exceeded ${MAX_ARTICLE_BYTES} bytes`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+            res.on('error', reject);
+        });
+        req.setTimeout(15_000, () => {
+            req.destroy(new Error('Failed to fetch article HTML: timed out after 15000ms'));
+        });
+        req.on('error', reject);
+        req.end();
     });
-    if (!response.ok) {
-        throw new Error(`Failed to fetch article HTML: ${response.statusText}`);
-    }
-    const html = await response.text();
+}
+export async function scrapeArticleLocal(url) {
+    // SSRF protection: reject private/internal URLs.
+    // Set PRISM_DEV_MODE=1 to allow loopback hosts during local dev (testing
+    // against a local docs server, internal wiki, etc.). The flag is
+    // intentionally OFF in production deploys.
+    const devMode = process.env.PRISM_DEV_MODE === '1' || process.env.NODE_ENV === 'development';
+    assertSafeScrapeTarget(url, devMode);
+    // Then resolve, validate every answer, and pin the connection to it.
+    const parsed = new URL(url);
+    const addresses = await resolveAndValidateHost(parsed.hostname, devMode);
+    const html = await fetchPinned(parsed, addresses);
     // Create a virtual DOM for Readability to traverse
     const doc = new JSDOM(html, { url });
     // Extract the article content like Firefox Reader View

package/dist/scholar/webScholar.js

@@ -1,4 +1,4 @@
-import { BRAVE_API_KEY, FIRECRAWL_API_KEY, GOOGLE_SEARCH_API_KEY, GOOGLE_SEARCH_CX, SEMANTIC_SCHOLAR_API_KEY, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN, PRISM_USER_ID, PRISM_SCHOLAR_TOPICS, PRISM_ENABLE_HIVEMIND, } from "../config.js";
+import { BRAVE_API_KEY, FIRECRAWL_API_KEY, GOOGLE_SEARCH_API_KEY, GOOGLE_SEARCH_CX, SEMANTIC_SCHOLAR_API_KEY, PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN, PRISM_USER_ID, PRISM_SCHOLAR_TOPICS, PRISM_ENABLE_HIVEMIND, PRISM_SCHOLAR_SCRAPE_BUDGET_MS, } from "../config.js";
 import { getStorage } from "../storage/index.js";
 import { debugLog } from "../utils/logger.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
@@ -238,15 +238,41 @@ export async function runWebScholar(overrideTopic, overrideProject) {
             return `No articles found for "${topic}"`;
         await hivemindHeartbeat(`Scraping ${urls.length} articles on: ${topic}`);
         const scrapedTexts = [];
+        const scrapeFailures = [];
+        // Scrapes run sequentially with a 15s per-fetch timeout, so N URLs cost
+        // up to N * 15s. PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN is env-overridable,
+        // so bound the whole loop rather than trusting the item count.
+        // A non-finite budget (bad env value, or a test that stubs the config
+        // module wholesale) must not silently disable scraping or the budget.
+        const budgetMs = Number.isFinite(PRISM_SCHOLAR_SCRAPE_BUDGET_MS) && PRISM_SCHOLAR_SCRAPE_BUDGET_MS > 0
+            ? PRISM_SCHOLAR_SCRAPE_BUDGET_MS
+            : 60_000;
+        const scrapeDeadline = Date.now() + budgetMs;
         for (const url of urls) {
+            if (Date.now() >= scrapeDeadline) {
+                scrapeFailures.push(`${url} — skipped: ${budgetMs}ms scrape budget exhausted`);
+                continue;
+            }
             try {
                 const article = await scrapeArticleLocal(url);
                 scrapedTexts.push(`Source: ${url}\nTitle: ${article.title}\n\n${article.content.slice(0, 15_000)}`);
             }
-            catch { }
+            catch (err) {
+                // A swallowed failure makes an empty run look identical to a good one.
+                const reason = err instanceof Error ? err.message : String(err);
+                scrapeFailures.push(`${url} — ${reason}`);
+                console.error(`[Scholar] scrape failed: ${url} — ${reason}`);
+            }
+        }
+        if (scrapedTexts.length === 0) {
+            const detail = scrapeFailures.length
+                ? `\n${scrapeFailures.join('\n')}`
+                : ' (no URLs attempted)';
+            return `All ${urls.length} scrape(s) failed for "${topic}":${detail}`;
+        }
+        if (scrapeFailures.length > 0) {
+            console.error(`[Scholar] ${scrapeFailures.length}/${urls.length} scrapes failed for "${topic}"`);
         }
-        if (scrapedTexts.length === 0)
-            return "All scrapes failed";
         await hivemindHeartbeat(`Synthesizing ${scrapedTexts.length} articles on: ${topic}`);
         const prompt = `You are an AI research assistant. Topic: "${topic}". Read these articles and write a comprehensive report.\n\n${scrapedTexts.join("\n---\n")}`;
         const llm = getLLMProvider();

package/docs/prism-browser.md

@@ -18,16 +18,100 @@ so a separate app or DMG is not required.
   scripts, allowing deterministic feature flags, fixtures, capability shims,
   or instrumentation for localhost tests.
 - **A constrained injection boundary.** Injection requires `--local-only`,
-  which rejects public navigation and non-loopback subrequests.
+  which rejects public navigation, non-loopback subrequests, service workers,
+  and WebSocket/EventSource/WebRTC egress.
 - **Private audit records.** The runner stores a local audit trail with private
   filesystem permissions and removes URL credentials, query strings,
-  fragments, common email/phone patterns, and injected source text.
+  fragments, common email/phone patterns, record identifiers in URL paths, and
+  injected source text.
+- **Failure signals instead of silence.** Console errors, uncaught page
+  exceptions, and failed requests are captured and attached to command output.
+  An HTTP status of 400 or higher, an empty screenshot frame, and a failed
+  assertion each produce a non-zero exit.
 
 These are orchestration and safety benefits. Prism Browser does not replace
 Playwright Test: use raw Playwright when you need its complete fixture,
 assertion, trace, project, or parallel-worker APIs. Compatibility patches are
 best effort and are not a CAPTCHA-bypass guarantee.
 
+## Assertions and exit codes
+
+A command reports `status: "ok"` only when it actually succeeded. Anything else
+(`failed`, `error`, `timeout`) marks the run, and `pipe` exits non-zero.
+
+```bash
+printf '%s\n' \
+  'open http://127.0.0.1:3000' \
+  'assert-title Dashboard' \
+  'assert-text #status Ready' \
+  'assert-count [data-row] 12' \
+  'assert-no-page-errors' \
+  | prism browser --headless --fast --fail-fast pipe
+```
+
+`eval` returns the native JSON value with its type, so results are machine
+readable:
+
+```json
+{"status": "ok", "result": {"a": 1}, "type": "dict", "serializable": true}
+```
+
+`assert-eval` is the assertion form — `eval` alone never fails a run, because a
+falsy expression is a legitimate result. Use `--fail-fast` for test runs so a
+failed navigation cannot be followed by commands that silently target the
+previous page.
+
+A trailing backslash continues a command onto the next line, which makes
+multi-line JavaScript and multi-line input text expressible. Quoted arguments
+are parsed with shell-style quoting, so `type "div > .cell" "two words"` works.
+
+## Hermetic runs
+
+Persistent profiles are convenient for interactive work and wrong for tests:
+state carries between runs and makes them order dependent. For test runs use
+
+- `--ephemeral-profile` — a throwaway profile directory, removed on exit.
+- `--storage-state PATH` — seed cookies and localStorage from a Playwright
+  storage-state file, so authenticated flows skip the login UI.
+- `save-storage PATH` — write the current state back out.
+- `--fast` — skip the human-latency emulation (per-character typing and
+  inter-action pauses), which otherwise dominates a test's wall clock.
+
+`--trace PATH`, `--video DIR`, and `--har PATH` record Playwright artifacts for
+a failing run.
+
+## Multiple pages
+
+A popup (OAuth, payment, print preview) opens a new page. `pages` lists them,
+`switch-page N` makes one active, and `close-page` disposes of it. Without
+switching, commands continue to target the original page.
+
+## Fingerprint patches
+
+`--stealth full` applies playwright-stealth, a CDP
+`Emulation.setUserAgentOverride` carrying full `userAgentMetadata`, and a
+supplementary init script. The CDP override is what keeps `navigator.userAgent`,
+`navigator.userAgentData`, and the `Sec-CH-UA` request headers consistent;
+rewriting headers through request interception does not work, because Chromium
+re-adds client hints after interception.
+
+Applied layers are verified rather than assumed. The runner probes the page for
+UA/brand/platform/webdriver agreement at startup and again after the first real
+navigation, and `--stealth full` fails with an actionable error when a requested
+layer cannot be applied. Pass `--allow-degraded-stealth` to proceed anyway, or
+`--stealth light` to skip the library layer deliberately. The `fingerprint`
+command reports the current state.
+
+These patches do not disable site isolation, client-side phishing detection, or
+popup blocking. Profiles hold live authenticated cookies, and trading away those
+mitigations for a fingerprint delta is the wrong exchange.
+
+## Profile maintenance
+
+Persistent profiles accumulate. `prism browser profiles` lists them by size and
+age; `--prune-older-than DAYS` reports what is stale and deletes it only when
+`--yes` is also passed.
+
 ## Install the local runtime
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.3.0",
+  "version": "20.3.2",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Prism Coder — Cognitive memory + tool-calling intelligence for AI agents. Mind Palace persistent memory (BFCL Gold Certified, 100% Tool-Call Accuracy, 114 Agent Skills, PHI Guard, Tier Enforcement, Prompt-Based Skill Routing, Zero-Search HDC/HRR retrieval, HRR Semantic Drift Detection across BCBA/Coding/AAC domains, HIPAA-hardened local or subscription-gated Synalux storage, SLERP-optimized GRPO alignment) plus the prism-coder 1.7B–32B open-weights LLM fleet.",
   "module": "index.ts",