prism-mcp-server 20.2.9 → 20.3.1

package/README.md

@@ -61,6 +61,41 @@ features.
 <details>
 <summary>Release history (optional)</summary>
 
+## 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
@@ -77,6 +112,21 @@ to the patched 8.5.23 release.
 
 ---
 
+## What's New in v20.3.0
+
+### Hybrid Memory Search (Portal Tier)
+
+`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
+lexical index.
+
 ## What's New in v20.2.6
 
 ### Safer Configuration Updates Across Every Agent

package/dist/storage/portalContracts.js

@@ -39,4 +39,8 @@ export const KnowledgeSearchResponseSchema = z.object({
     action: z.literal("knowledge_search"),
     count: z.number(),
     results: z.array(z.record(z.string(), z.unknown())),
+    /** How the portal matched. Optional so an older portal deployment that
+     *  predates the ranked search RPC still validates. When present and
+     *  'relaxed', callers MUST NOT present the rows as exact hits. */
+    match_mode: z.enum(["strict", "relaxed", "unfiltered", "none"]).optional(),
 });

package/dist/storage/synalux.js

@@ -25,17 +25,30 @@
  *     - searchKnowledge   → POST /api/v1/prism/memory  action=search
  *     - softDeleteLedger  → POST /api/v1/prism/memory  action=forget_memory (Phase 3 Tier A)
  *     - hardDeleteLedger  → POST /api/v1/prism/memory  action=forget_memory (Phase 3 Tier A)
+ *     - searchMemory      → POST /api/v1/prism/memory  action=search_memory
+ *     - getHistory        → POST /api/v1/prism/memory  action=memory_history
+ *     - patchLedger       → POST /api/v1/prism/memory  action=save_embedding
+ *     - getEntriesMissingEmbeddings → POST /api/v1/prism/memory  action=list_missing_embeddings
  *
  *   Methods still falling through to SupabaseStorage (Phase 3 Tier B+):
- *   semantic searchMemory, save_experience direct entrypoint,
- *   compactLedger, image ops, history, hivemind, etc.
+ *   save_experience direct entrypoint, compactLedger, image ops,
+ *   hivemind, etc. Anything in this group requires a direct SUPABASE_URL
+ *   and therefore does NOT work on paid-tier installs — that is precisely
+ *   how embedding writes failed silently: patchLedger was inherited, threw
+ *   against a URL that is not configured, and the caller swallowed it.
+ *   Before relying on an inherited method, check it is actually reachable.
+ *
+ *   NOTE: this list was previously wrong — it named searchMemory and
+ *   history as falling through when both had already been overridden.
+ *   A stale routing map here sends the next reader down the wrong path,
+ *   so amend it in the same commit that moves a method.
  *   See portal/docs/PHASE_3_PORTAL_ENDPOINTS.md for the full catalog.
  * ═══════════════════════════════════════════════════════════════════
  */
 import { SupabaseStorage } from "./supabase.js";
 import { debugLog } from "../utils/logger.js";
 import { PRISM_SYNALUX_BASE_URL, PRISM_SYNALUX_API_KEY } from "../config.js";
-import { KnowledgeSearchRequestSchema } from "./portalContracts.js";
+import { KnowledgeSearchRequestSchema, KnowledgeSearchResponseSchema } from "./portalContracts.js";
 function resolveKnowledgeScope(callerScope) {
     if (callerScope === "user" || callerScope === "workspace") {
         return callerScope;
@@ -330,6 +343,8 @@ export class SynaluxStorage extends SupabaseStorage {
         const result = await this.portalPost("/api/v1/prism/memory", {
             action: "search_memory",
             project: params.project ?? undefined,
+            // Enables the portal's hybrid lexical+semantic fusion (see interface).
+            query: params.queryText || undefined,
             query_embedding: parsed,
             similarity_threshold: params.similarityThreshold,
             limit: params.limit,
@@ -358,9 +373,81 @@ export class SynaluxStorage extends SupabaseStorage {
             scope: resolveKnowledgeScope(params.scope),
         });
         const result = await this.portalPost("/api/v1/prism/memory", wireBody);
+        // Validate the RESPONSE against the shared contract, not just the request.
+        // Before this, only the outgoing shape was checked — so a portal-side
+        // field rename would have gone unnoticed on both sides, which is exactly
+        // the 2026-05-24 class of incident this file exists to prevent.
+        // safeParse (not parse) on purpose: drift must be loud, but it must not
+        // take knowledge_search offline. The build-time contract test is what
+        // fails hard; at runtime we log and degrade to lenient extraction.
+        const validated = KnowledgeSearchResponseSchema.safeParse(result);
+        if (!validated.success) {
+            console.error("[synalux] knowledge_search response failed contract validation — " +
+                "portal and client may have drifted: " +
+                JSON.stringify(validated.error.issues.map(i => ({ path: i.path, code: i.code }))));
+        }
         const count = typeof result.count === "number" ? result.count : 0;
         const results = Array.isArray(result.results) ? result.results : [];
-        return { count, results };
+        const matchMode = validated.success ? validated.data.match_mode : undefined;
+        return { count, results, match_mode: matchMode };
+    }
+    /**
+     * Persist embedding data for an already-saved entry.
+     *
+     * MUST be overridden here. SupabaseStorage.patchLedger writes straight to
+     * Supabase via supabasePatch, which needs a direct SUPABASE_URL — not
+     * configured for paid-tier installs. Inheriting it meant every embedding
+     * write threw, and session_save_ledger's fire-and-forget catch swallowed
+     * the error while still reporting "Embedding generation queued". The
+     * result was 0 of 8,560 rows carrying an embedding and semantic search
+     * silently returning nothing.
+     *
+     * Only the vector is sent. embedding_compressed / embedding_format /
+     * embedding_turbo_radius are local-SQLite columns that do not exist on the
+     * portal schema; forwarding them would fail the whole write for fields the
+     * server has nowhere to put.
+     */
+    async patchLedger(id, data) {
+        const raw = data.embedding;
+        if (raw === undefined || raw === null)
+            return;
+        // ledgerHandlers JSON-stringifies the vector before patching; accept both.
+        let vector = raw;
+        if (typeof raw === "string") {
+            try {
+                vector = JSON.parse(raw);
+            }
+            catch {
+                throw new Error("patchLedger: embedding string is not valid JSON");
+            }
+        }
+        if (!Array.isArray(vector)) {
+            throw new Error("patchLedger: embedding must be an array");
+        }
+        await this.portalPost("/api/v1/prism/memory", {
+            action: "save_embedding",
+            memory_id: id,
+            embedding: vector,
+        });
+    }
+    /**
+     * Rows semantic search cannot find, read through the portal.
+     *
+     * The backfill tool used to reach these via inherited getLedgerEntries —
+     * a direct Supabase read paid-tier installs cannot make (NXDOMAIN), so the
+     * repair tool could never see what needed repairing. The portal endpoint
+     * ignores cursorId (it always returns the oldest missing rows, and rows
+     * gain embeddings as the backfill proceeds, so the frontier advances by
+     * itself); it is accepted here to satisfy the shared signature.
+     */
+    async getEntriesMissingEmbeddings(params) {
+        const result = await this.portalPost("/api/v1/prism/memory", {
+            action: "list_missing_embeddings",
+            limit: params.limit,
+            ...(params.project ? { project: params.project } : {}),
+        });
+        const entries = Array.isArray(result.entries) ? result.entries : [];
+        return entries;
     }
     // ─── Time Travel ─────────────────────────────────────────────
     // Phase 3 Tier B: route memory_history through portal instead of
@@ -397,8 +484,15 @@ export class SynaluxStorage extends SupabaseStorage {
             const inventory = result.inventory;
             const totalActiveEntries = typeof inventory?.ledger_entries === "number" ? inventory.ledger_entries : 0;
             const totalHandoffs = typeof inventory?.active_projects === "number" ? inventory.active_projects : 0;
+            // Hardcoding 0 here certified a 100%-missing-embeddings outage as
+            // "HEALTHY — all clean". Use the portal's real count; if the portal
+            // predates the field, report -1 so healthCheck can say "unknown"
+            // instead of lying in either direction.
+            const missingEmbeddings = typeof inventory?.ledger_missing_embeddings === "number"
+                ? inventory.ledger_missing_embeddings
+                : -1;
             return {
-                missingEmbeddings: 0,
+                missingEmbeddings,
                 activeLedgerSummaries: [],
                 orphanedHandoffs: [],
                 staleRollups: 0,
@@ -411,7 +505,9 @@ export class SynaluxStorage extends SupabaseStorage {
         catch (e) {
             debugLog("[SynaluxStorage] getHealthStats failed: " + (e instanceof Error ? e.message : String(e)));
             return {
-                missingEmbeddings: 0,
+                // Portal unreachable: coverage is UNKNOWN, not zero. -1 makes the
+                // health check say so rather than certify blind.
+                missingEmbeddings: -1,
                 activeLedgerSummaries: [],
                 orphanedHandoffs: [],
                 staleRollups: 0,

package/dist/tools/graphHandlers.js

@@ -57,6 +57,56 @@ import { ConceptDictionary } from "../sdm/conceptDictionary.js";
 import { PolicyGateway } from "../sdm/policyGateway.js";
 import { getSdmEngine } from "../sdm/sdmEngine.js";
 import { PRISM_HDC_ENABLED, PRISM_HDC_EXPLAINABILITY_ENABLED, PRISM_HDC_POLICY_FALLBACK_THRESHOLD, PRISM_HDC_POLICY_CLARIFY_THRESHOLD, } from "../config.js";
+/**
+ * Header line for knowledge_search results.
+ *
+ * A 'relaxed' match_mode means no entry matched every query term — the portal
+ * widened the search and returned the closest entries. Wording those the same
+ * as an exact hit is how a best-effort guess gets read as a confirmed answer,
+ * so the distinction is stated in the text the agent actually sees.
+ *
+ * Exported so the wording is covered by a test that exercises this function
+ * rather than a copy of it.
+ */
+export function formatKnowledgeHeader(resultCount, matchMode) {
+    if (matchMode === "relaxed") {
+        return `🧠 No exact match. ${resultCount} closest ${resultCount === 1 ? "entry" : "entries"} ` +
+            `(widened search — treat as leads, not confirmed answers):`;
+    }
+    return `🧠 Found ${resultCount} knowledge entries:`;
+}
+/**
+ * Header + per-hit scoring for session_search_memory results.
+ *
+ * Exported so wording is covered by tests that call the shipped functions —
+ * a lesson from the knowledge_search match_mode fix, whose first tests
+ * mirrored the logic and would have passed while the handler regressed.
+ *
+ * Hybrid detection is per-row: portal fusion (weighted RRF, measured 59%
+ * blind hit@1 vs 45% semantic-only) annotates each row with semantic_rank /
+ * lexical_rank. Any row carrying lexical_rank means the lexical arm ran, so
+ * calling the results "semantically similar" would misstate how they were
+ * found — and a lexical-only rescue has NO similarity score at all, which
+ * previously rendered as "N/A similar".
+ */
+export function isHybridSearchResults(results) {
+    return results.some((r) => r?.lexical_rank !== undefined && r?.lexical_rank !== null);
+}
+export function searchResultsHeader(count, hybrid) {
+    return hybrid
+        ? `🧠 Found ${count} matching sessions (hybrid retrieval — semantic meaning + exact terms):`
+        : `🧠 Found ${count} semantically similar sessions:`;
+}
+export function formatHitScore(r) {
+    const sim = typeof r.similarity === "number" ? `${(r.similarity * 100).toFixed(1)}% similar` : null;
+    const sem = r.semantic_rank !== undefined && r.semantic_rank !== null ? `sem#${r.semantic_rank + 1}` : null;
+    const lex = r.lexical_rank !== undefined && r.lexical_rank !== null ? `lex#${r.lexical_rank + 1}` : null;
+    if (sem || lex) {
+        const arms = [sem, lex].filter(Boolean).join(" + ");
+        return sim ? `${sim} (${arms})` : `exact-term match (${arms})`;
+    }
+    return sim ?? "N/A similar";
+}
 export async function knowledgeSearchHandler(args) {
     if (!isKnowledgeSearchArgs(args)) {
         throw new Error("Invalid arguments for knowledge_search");
@@ -136,7 +186,7 @@ export async function knowledgeSearchHandler(args) {
     // Phase 1: Wrap in contentBlocks array for optional trace attachment
     const contentBlocks = [{
             type: "text",
-            text: `🧠 Found ${resultCount} knowledge entries:\n\n${JSON.stringify(data.results, null, 2)}`,
+            text: `${formatKnowledgeHeader(resultCount, data.match_mode)}\n\n${JSON.stringify(data.results, null, 2)}`,
         }];
     // Phase 1: Attach MemoryTrace with strategy="keyword" and timing data
     if (enable_trace) {
@@ -377,6 +427,8 @@ export async function sessionSearchMemoryHandler(args) {
             : Math.min(limit, 20);
         const results = await storage.searchMemory({
             queryEmbedding: JSON.stringify(queryEmbedding),
+            // Portal-backed installs fuse this with lexical search (weighted RRF).
+            queryText: query,
             project: project || null,
             limit: candidateLimit,
             similarityThreshold: similarity_threshold,
@@ -516,9 +568,7 @@ export async function sessionSearchMemoryHandler(args) {
         }
         // Format results with similarity scores + effective importance + ACT-R
         const formatted = results.map((r, i) => {
-            const simScore = typeof r.similarity === "number"
-                ? `${(r.similarity * 100).toFixed(1)}%`
-                : "N/A";
+            const simScore = formatHitScore(r);
             // Dynamic importance decay (uses ACT-R internally when enabled)
             const baseImportance = r.importance ?? 0;
             const effectiveImportance = computeEffectiveImportance(baseImportance, r.last_accessed_at, r.created_at, Boolean(r.is_rollup));
@@ -529,7 +579,7 @@ export async function sessionSearchMemoryHandler(args) {
             const actrStr = r._actr_composite !== undefined
                 ? `  ACT-R: composite=${r._actr_composite.toFixed(3)} (B=${r._actr_Bi?.toFixed(2)}, S=${r._actr_Si?.toFixed(3)})\n`
                 : "";
-            return `[${i + 1}] ${simScore} similar — ${r.session_date || "unknown date"}\n` +
+            return `[${i + 1}] ${simScore} — ${r.session_date || "unknown date"}\n` +
                 `  Project: ${r.project}\n` +
                 `  Summary: ${r.summary}\n` +
                 importanceStr +
@@ -540,7 +590,7 @@ export async function sessionSearchMemoryHandler(args) {
         // Phase 1: content[0] = human-readable results (unchanged from pre-Phase 1)
         const contentBlocks = [{
                 type: "text",
-                text: `🧠 Found ${results.length} semantically similar sessions:\n\n${formatted}`,
+                text: `${searchResultsHeader(results.length, isHybridSearchResults(results))}\n\n${formatted}`,
             }];
         // Phase 1: content[1] = machine-readable MemoryTrace (only when enable_trace=true)
         // topScore is read from results[0].similarity — this is the cosine distance

package/dist/tools/hygieneHandlers.js

@@ -60,22 +60,36 @@ export async function backfillEmbeddingsHandler(args) {
     debugLog(`[backfill_embeddings] ${dry_run ? "DRY RUN: " : ""}` +
         `project=${project || "all"}, limit=${safeLimit}`);
     const storage = await getStorage();
-    // Find entries missing embeddings
-    const params = {
-        "embedding": "is.null",
-        "archived_at": "is.null",
-        user_id: `eq.${PRISM_USER_ID}`,
-        order: "id.asc",
-        limit: String(safeLimit),
-        select: "id,summary,decisions,project",
-    };
-    if (args._cursor_id) {
-        params.id = `gt.${args._cursor_id}`;
+    // Find entries missing embeddings. Prefer the dedicated method: the old
+    // PostgREST-param path below goes through getLedgerEntries, which
+    // SynaluxStorage inherits as a DIRECT Supabase read — paid-tier installs
+    // have no SUPABASE_URL, so that read dies with NXDOMAIN and this tool
+    // could never see what it was supposed to repair.
+    let entries;
+    if (typeof storage.getEntriesMissingEmbeddings === "function") {
+        entries = await storage.getEntriesMissingEmbeddings({
+            limit: safeLimit,
+            ...(project ? { project } : {}),
+            ...(args._cursor_id ? { cursorId: args._cursor_id } : {}),
+        });
     }
-    if (project) {
-        params.project = `eq.${project}`;
+    else {
+        const params = {
+            "embedding": "is.null",
+            "archived_at": "is.null",
+            user_id: `eq.${PRISM_USER_ID}`,
+            order: "id.asc",
+            limit: String(safeLimit),
+            select: "id,summary,decisions,project",
+        };
+        if (args._cursor_id) {
+            params.id = `gt.${args._cursor_id}`;
+        }
+        if (project) {
+            params.project = `eq.${project}`;
+        }
+        entries = await storage.getLedgerEntries(params);
     }
-    const entries = await storage.getLedgerEntries(params);
     if (entries.length === 0) {
         return {
             content: [{

package/dist/tools/ledgerHandlers.js

@@ -627,6 +627,7 @@ export async function sessionSaveHandoffHandler(args, server) {
     // Await the attempt so short-lived CLI/MCP transports cannot exit before the
     // snapshot reaches storage. Failure stays non-fatal because the primary
     // handoff has already been durably saved.
+    let historySnapshotSaved = false;
     if (data.status === "created" || data.status === "updated") {
         const snapshotEntry = {
             project,
@@ -637,10 +638,12 @@ export async function sessionSaveHandoffHandler(args, server) {
             keywords: keywords ?? null,
             key_context: key_context ?? null,
             active_branch: active_branch ?? null,
+            role: effectiveRole,
             version: newVersion,
         };
         try {
-            await storage.saveHistorySnapshot(snapshotEntry);
+            await storage.saveHistorySnapshot(snapshotEntry, active_branch ?? "main");
+            historySnapshotSaved = true;
         }
         catch (err) {
             console.error(`[session_save_handoff] History snapshot failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
@@ -800,12 +803,16 @@ export async function sessionSaveHandoffHandler(args, server) {
         console.error("[FactMerger] Module load failed (non-fatal): " + err));
     }
     const metricsBlock = formatInferenceMetrics();
+    const historySnapshotLine = historySnapshotSaved
+        ? `🕘 Versioned history snapshot saved.\n`
+        : `⚠️ Primary handoff saved, but its versioned history snapshot was not saved. Check memory_history before relying on time travel.\n`;
     // Build response text based on whether a CRDT merge occurred
     const responseText = (_saveHandoffGateWarning ? `⚠️ ${_saveHandoffGateWarning}\n\n` : "") +
         (isMerged
             ? `🔄 Auto-merged conflict for "${project}" (v${expected_version} → v${newVersion})\n` +
                 `Strategy: ${JSON.stringify(mergeStrategy)}\n` +
                 (last_summary ? `Summary: ${last_summary}\n` : "") +
+                historySnapshotLine +
                 metricsBlock +
                 `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
                 `to maintain concurrency control.`
@@ -814,6 +821,7 @@ export async function sessionSaveHandoffHandler(args, server) {
                 (last_summary ? `Last summary: ${last_summary}\n` : "") +
                 (open_todos?.length ? `Open TODOs: ${open_todos.length} items\n` : "") +
                 (active_branch ? `Active branch: ${active_branch}\n` : "") +
+                historySnapshotLine +
                 (embeddingQueued
                     ? `📊 Embedding generation queued for semantic search.\n`
                     : `📊 Primary history saved; optional semantic indexing was not queued.\n`) +

package/dist/utils/healthCheck.js

@@ -217,7 +217,21 @@ export function runHealthCheck(stats) {
             severity: stats.missingEmbeddings > 10 ? "error" : "warning", // >10 = critical
             message: `${stats.missingEmbeddings} ledger entries have no embedding vector`,
             count: stats.missingEmbeddings, // how many are affected
-            suggestion: "Run session_health_check(auto_fix: true) to generate missing embeddings automatically",
+            suggestion: "Run session_backfill_embeddings to generate the missing vectors",
+        });
+    }
+    else if (stats.missingEmbeddings < 0) {
+        // -1 = coverage is UNKNOWN (portal unreachable, or a portal that predates
+        // the ledger_missing_embeddings field). Saying nothing here is how a
+        // 100%-missing outage was certified "HEALTHY — all clean": the storage
+        // layer hardcoded 0 and this check had no way to distinguish "verified
+        // zero" from "never looked".
+        issues.push({
+            check: "missing_embeddings",
+            severity: "warning",
+            message: "Embedding coverage could not be verified (portal did not report a count)",
+            count: 0,
+            suggestion: "Update the Synalux portal, or check connectivity, then re-run session_health_check",
         });
     }
     // ── Check 2: Duplicate Entries ─────────────────────────────

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.2.9",
+  "version": "20.3.1",
   "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",